A lightweight, themeable multi-select web component with typeahead search, RTL support, rich content, and full keyboard navigation.
- 🚀 Showcase
- 🧪 Live demo
- 📘 Usage / API reference — attributes, properties, methods, events.
- 🎨 Theming —
--ms-*variables, dark mode, cascade layers, Theme Designer integration. - 📚 Examples / cookbook — rich content, async search, virtual scroll, custom rendering, forms.
- ♿ Accessibility — keyboard model, ARIA labels, focus behavior.
@keenmate/web-multiselect is a custom element (<web-multiselect>) that turns a list of options into a searchable, themeable multi-select dropdown. Framework-agnostic — works in React, Vue, Svelte, Blazor, plain HTML.
Reads the --base-* tokens from @keenmate/base-css-variables 2.0 when the page loads them (the shared layer behind pure-admin and the Theme Designer), falls back to sensible OS-aware defaults otherwise, and ships with first-class dark-mode and per-instance theming.
Headline features:
- Declarative
<option>/<optgroup>markup — no JavaScript required for simple cases. - Virtual scrolling for 10,000+ option datasets (25× faster opening, 99.8% memory reduction).
- Filter or navigate search modes; async / hybrid search.
- Five badge display modes (badges, count, compact, partial, none) with positioning on any side.
- Tree mode with cascade / independent checkboxes; phone-friendly fullscreen presentation.
- Full keyboard navigation, RTL language support, badge tooltips.
- Custom rendering callbacks for options, badges, and group headers.
- Form integration via standard hidden inputs (FormData-compatible).
Upgrade guide: the 3.0.0-rc03 release notes; full list: the CHANGELOG 3.0.0-rc03 section.
- Phone sheets — core's sheet chrome,
--ms-sheet-*variables — The fullscreen dropdown and the fullscreen selected-items popover now draw their top bar, title and ✕ with core's shared sheet chrome, so they look like every other Keenmate phone sheet (a 44px close chip, the--base-icon-closeglyph). The bar's variables are renamed from--ms-fullscreen-header-*/-title-*/-close-*to--ms-sheet-*, with the same 19 suffixes as core's page-wide--km-sheet-*. They are unset by default, and the--ms-fullscreen-header-paddingshorthand is gone. Back still closes the sheet, now through coreclaimBackEntry(), and the page keeps its scroll position. - Dropdown — closes on scroll, says why it closed — The dropdown runs on core
createPopover()and, like a native select, now closes when the page or a scroller around it scrolls (close-on-scroll, defaulttrue; a scroll inside the list never closes it). Thecloseevent carriesdetail.reason(escape,outside-click,scroll,select,reference-removed, …). The selected-items popover moved to core's overlay tree too, so opening another overlay closes it. - Inputs — length inputs are CSS lengths —
dropdown-min-width,dropdown-max-width,max-height,dropdown-widthandselected-popover-widthare parsed by coretoCssLength(). A bare number means px, an invalid length ornullis refused with aninput-rejectedevent, and removing the attribute resets it. - Messages —
variantanddanger—showMessage()takes{ variant }instead of{ type }, and'error'is now'danger', matching the rest of Keenmate. The class is.ms__message--dangerand the variables are--ms-message-danger-bg/-color. There are no aliases. - Scrolling —
beforeScrollCallback— Every scroll the dropdown does on its own (keyboard moves, navigate-mode search, revealing the selection on open,scrollToIndex/scrollToValue/scrollToGroup) now goes throughbeforeScrollCallback(ctx). Returnfalseto skip it, or{ block, behavior }to change it.ctx.sourcesays what triggered it. Virtual lists also honour--ms-options-paddingandscroll-paddingon a jump, so the last row comes fully into view. - Theming — page-wide custom CSS, tooltip widths, dropdown gap —
window.components['web-multiselect'].customStylesstyles every instance (an instance's owncustomStylesstill wins), and an@importin it now registers icon fonts. New--ms-tooltip-width/--ms-tooltip-min-width(with option-tooltip twins) complete the tooltip width model. The field-to-panel gap is the page token--base-dropdown-offset. - Fixes — controller under disabled / readonly, WebKit Backspace —
el.controller.selectAll(),selectValue(),clearSelection()and the other selection methods used to be silently ignored on a disabled or readonly control; calls from code now work, and only user gestures are blocked. In Safari, Backspace in a read-only input no longer navigates the page Back.
Upgrade guide: the 3.0.0-rc02 release notes; full list: the CHANGELOG 3.0.0-rc02 section.
- Inputs — strict values (core rc18) — Attribute and property writes are validated strictly by
@keenmate/web-components-core1.0.0-rc18. A number with a unit or a fraction (badge-height="24px",virtual-scroll-item-height="1.5") used to be silently truncated; it is now refused with a warning and a newinput-rejectedevent, and the previous value is kept. Enum values match case-insensitively, andel.x = undefinedresets an input to its default instead of being rejected. Pixel attributes take a bare integer. - Search —
search-input-moderemoved,enable-search="false"is a real picker —search-input-mode(readonly/hidden) only repeatedenable-search="false"with a stranger fullscreen header and, forhidden, an invisible single-select label, so it is gone. The search-off picker itself was fixed: the input is natively read-only (no caret, no soft keyboard on phones), the shown value can be selected and copied, Escape closes in one press instead of erasing the label first, and the fullscreen sheet's ✕ sits at the trailing edge, centred. - Loader — classes renamed — The default spinner is
.ms__loader(was.ms-loader) and the dropdown's loading-state container is.ms__loading(was.ms__loader), following core rc18's shared loader. Page CSS orcustom-stylesthat targeted the old classes must be renamed; the--ms-loader-*tokens keep their names. - Keyboard — arrow keys skip disabled options — Arrow keys, Home / End, Page Up / Down and navigate-mode Ctrl + arrows never land on a disabled option, nor does the auto-focus of the first search result or the selected option on open. Before, the highlight stopped on a disabled row and its focus ring disappeared under the disabled styling. This matches core's menus and the MUI / Radix / React Aria defaults.
- Overlays — dropdowns inside modals and popovers — The dropdown joins core's overlay tree, so opening a multiselect inside an open modal, popover or dropdown no longer dismisses that container, and closing the container closes the dropdown. The standalone engine mounts its panels in the nearest open modal
<dialog>or:popover-openelement instead of<body>, where they were inert behind the modal. - Tooltips and layout — visible fixes — Option tooltips no longer stop showing after the first pick with the dropdown open; each tooltip owner now has its own id prefix, so a value like
option-0can't take over another tooltip.checkbox-align="top"puts the checkbox on the first text line (first baseline), so tall custom-rendered rows line up. Disabled and readonly controls no longer draw a remove ✕ on badges, and the fullscreen search clear uses the themeable field-clear ✕. - Data — quotes in values, corrected security notice — An option value containing a quote (
say "hi") cut itsdata-valueattribute short, so the wrong value was selected and the badge couldn't be removed; option values and tree paths are now escaped. The README's XSS notice is corrected: display values, full titles, subtitles and icons are HTML by design and must be sanitized when untrusted. - Logging — closest level wins — Log levels coalesce element → type → page →
warn, every warning now goes through the loggers (sodisableLogging()silences them all), and a newresetLogging()clears an element's or type's own level.
Earlier releases: 3.0.0-rc01, 2.6.0-rc03, 2.6.0-rc02, CHANGELOG.
npm install @keenmate/web-multiselectDeclarative — no JavaScript required:
<script type="module">
import '@keenmate/web-multiselect';
</script>
<web-multiselect labels='{"selectPlaceholder": "Pick a country"}'>
<option value="cz">Czech Republic</option>
<option value="sk">Slovakia</option>
<option value="at">Austria</option>
</web-multiselect>Programmatic — dynamic data + events:
<web-multiselect id="picker" labels='{"searchPlaceholder": "Search…"}'></web-multiselect>
<script type="module">
import '@keenmate/web-multiselect';
const picker = document.getElementById('picker');
picker.options = [
{ value: 'js', label: 'JavaScript', icon: '🟨' },
{ value: 'ts', label: 'TypeScript', icon: '🔷' },
{ value: 'py', label: 'Python', icon: '🐍' }
];
picker.addEventListener('change', (e) => {
console.log('Selected:', e.detail.selectedValues);
});
</script>See docs/usage.md for the full API and docs/examples.md for advanced patterns (async data, virtual scrolling, custom rendering, form integration).
Tune what the picker does per device or window width without app-side viewport code — a map
of partial configs, or a callback that computes one. A map has two axes, each keyed
mobile / tablet / desktop:
device— the device class (classifyDevice): a phone / tablet by capability (touch-primary, then the short side); a mouse device isdesktopat any width.breakpoint— the window width bucket (768 / 1024px lines,--base-breakpoint-*): a narrowed desktop window ismobilebelow 768px.
Within one map the breakpoint entry applies first and the device entry over it (device wins
on the same key). Own widths or combinations (ctx.env.viewportWidth, device class AND
width, …) go in a responsiveCallback. Keys are configKeys; set them page-wide, per tag
or per instance
(the generic core mechanism, core SPEC §6.7):
// page-wide (every Keenmate component) and per tag — may be set before the script loads
window.components.responsive = { device: { mobile: { presentation: 'fullscreen' } } };
window.components['web-multiselect'].responsiveCallback = (ctx) =>
ctx.deviceClass === 'mobile' ? { actionsLayout: 'wrap' } : undefined;
// per instance (property, or the JSON attribute responsive='{"device":{"tablet":{…}}}')
el.responsive = {
device: { tablet: { presentation: 'fullscreen' } }, // a touch tablet
breakpoint: { mobile: { badgesDisplayMode: 'count' } }, // any window under 768px
};
el.responsiveCallback = (ctx) => (ctx.env.orientation === 'landscape' ? { badgesThreshold: 5 } : undefined);Precedence (later wins, key by key): global map → global callback → per-tag map → per-tag
callback → the instance's own attributes / properties → instance map → instance callback.
An attribute written on an element is never overridden by a page rule; null from the
instance callback ignores every page rule. Maps re-run when the device class / breakpoint
changes, callbacks also on every viewport resize; overrides never reflect to attributes. The
pre-rc15 device-keyed shape ({ mobile: … }) warns and is ignored. Typed as MultiSelectResponsiveMap /
MultiSelectResponsiveCallback. Demo: examples-responsive.html, examples-action-buttons.html.
Errors and warnings print out of the box (the default level is warn); info / debug / trace are
opt-in. Levels coalesce, closest first:
| Scope | API |
|---|---|
| Element | el.enableLogging(level?) (default debug; 'error' makes it quieter than its type), el.disableLogging() silences this element, el.resetLogging() — it follows its type / the page again |
Type (per category INIT / DATA / UI / INTERACTION) |
window.components['web-multiselect'].logging — enableLogging, disableLogging, setLogLevel, setCategoryLevel(cat, level | null), resetLogging; the same functions are exported from the package |
| Page | window.components.logging — every component on the page |
| Default | warn |
A page call never overwrites a type level, so the order of calls doesn't matter. Instance
debug / trace lines print through console.log. See examples-logging.html.
The package ships editor metadata so you get autocomplete and hover docs for the
element's attributes, events, and all --ms-* CSS custom properties. All of it is
generated from the component's source on every build, so it never drifts.
-
JetBrains (WebStorm / IntelliJ) — works automatically. The IDE discovers
web-types.jsonvia theweb-typesfield inpackage.json; no setup needed. -
VS Code — the data files ship but VS Code doesn't auto-discover them from a dependency, so point your workspace at them once in
.vscode/settings.json:{ "html.customData": [ "./node_modules/@keenmate/web-multiselect/vscode.html-custom-data.json" ], "css.customData": [ "./node_modules/@keenmate/web-multiselect/vscode.css-custom-data.json" ] }html.customDatapowers tag/attribute completion on<web-multiselect>;css.customDatapowers completion for the--ms-*theming variables. Reload the window after adding them.
These inputs are inserted as raw HTML — intentionally not XSS-safe, so you control the markup. Sanitize any untrusted text before passing it in:
| Input | Output used in |
|---|---|
labels.noData, labels.noResults, labels.searching |
Dropdown empty / searching text (innerHTML) |
labels.addNew, labels.addNewPending |
"Add new" prompt (innerHTML; the {value} typed text is escaped) |
labels.selectedCount, labels.moreCount |
Counter badge text (innerHTML) |
renderOptionContentCallback, renderGroupLabelContentCallback, renderBadgeContentCallback, renderBadgeCallback, renderSelectedItemContentCallback (string return) |
Option rows, group headers, badges, selected panels (innerHTML) |
Display value (displayValueMember / getDisplayValueCallback) |
Option title and badge text (innerHTML; search highlighting marks text runs only) |
getBadgeDisplayCallback |
Badge text (innerHTML) |
Full title (fullTitleMember / getFullTitleCallback) |
Badge text when isBadgeFullTitleShown (innerHTML) |
Subtitle (subtitleMember / getSubtitleCallback) |
Option subtitle (innerHTML) |
Icon (iconMember / getIconCallback) |
Option icon (innerHTML) |
All other labels (ARIA labels, tooltips, placeholders, popover title, action-button texts) are
plain text, as are showMessage() strings and renderSelectedContentCallback (the closed input's value).
Option values and tree paths are escaped (they only ever land in attributes); the display value,
full title, subtitle and icon are HTML — sanitize untrusted data first.
Modern evergreen browsers — the standalone colour fallbacks use CSS relative-colour syntax (oklch(from …)), the same floor as @keenmate/base-css-variables 2.x:
- Chrome / Edge 119+
- Firefox 128+
- Safari 18+
No polyfills are shipped. SSR-safe: the module imports without crashing in Node, but renders only after hydration in the browser.
# Install dependencies
npm install
# Start dev server (HMR)
npm run dev
# Build for production
npm run build
# Create package tarball
npm run package
# Run tests
npm run test:unit # Vitest (happy-dom) — fast logic checks
npm run test:e2e # Playwright (browser) — interaction/visual
npm test # bothFollows the BlissFramework four-layer web-component layout:
| Layer | File | Role |
|---|---|---|
| Element | src/web-component.ts |
MultiSelectElement — custom-element I/O wrapper, driven by the INPUTS table (attributes, properties, callbacks) and the events table |
| Logic | src/multiselect.ts |
MultiSelectEngine<T> — framework-agnostic core (search, selection, keyboard, rendering) |
| Service | src/virtual-scroll.ts, src/tree/ |
VirtualScroll; the ltree option model and checkbox cascade for tree mode |
| Side | src/types.ts, src/option-formats.ts, src/converters.ts, src/logger.ts, src/index.ts |
types, data-options parsers, component-local converters, logging shim, package entry |
Positioning (dropdown, popovers, tooltips), attribute parsing and reflection, and the logging engine come from @keenmate/web-components-core.
Two deviations from the canonical shape, both intentional:
MultiSelectElement extends BlissElement, notHTMLElementdirectly. Core'sBlissElementresolves toHTMLElementin the browser and to a stub class under SSR (typeof HTMLElement === 'undefined'), so importing the module in Node doesn't throw. A literalgrep "extends HTMLElement"structure check will not match here by design.src/vite-env.d.tsis a standard Vite ambient-types file, not part of the four-layer model.
MIT — see LICENSE.
Follows the BlissFramework component guidelines for structure, theming, color-scheme, and accessibility. Per-check verifications run via /validate-web-component.
Created by Keenmate as part of the Pure Admin design system.