Skip to content

About

A modern, framework-agnostic multi-select dropdown component built as a web component. Features RTL language support, async search, flexible data handling, form integration, multiple display modes, and extensive SCSS customization.

Topics

Resources

Accessibility

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

306 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@keenmate/web-multiselect

License: MIT npm version

A lightweight, themeable multi-select web component with typeahead search, RTL support, rich content, and full keyboard navigation.

Demos & docs

What is it

@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).

What's New in v3.0.0-rc03

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-close glyph). 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-padding shorthand is gone. Back still closes the sheet, now through core claimBackEntry(), 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, default true; a scroll inside the list never closes it). The close event carries detail.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-width and selected-popover-width are parsed by core toCssLength(). A bare number means px, an invalid length or null is refused with an input-rejected event, and removing the attribute resets it.
  • Messages — variant and danger — showMessage() takes { variant } instead of { type }, and 'error' is now 'danger', matching the rest of Keenmate. The class is .ms__message--danger and 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 through beforeScrollCallback(ctx). Return false to skip it, or { block, behavior } to change it. ctx.source says what triggered it. Virtual lists also honour --ms-options-padding and scroll-padding on a jump, so the last row comes fully into view.
  • Theming — page-wide custom CSS, tooltip widths, dropdown gap — window.components['web-multiselect'].customStyles styles every instance (an instance's own customStyles still wins), and an @import in 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.

What's New in v3.0.0-rc02

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-core 1.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 new input-rejected event, and the previous value is kept. Enum values match case-insensitively, and el.x = undefined resets an input to its default instead of being rejected. Pixel attributes take a bare integer.
  • Search — search-input-mode removed, enable-search="false" is a real picker — search-input-mode (readonly / hidden) only repeated enable-search="false" with a stranger fullscreen header and, for hidden, 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 or custom-styles that 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-open element 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-0 can'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 its data-value attribute 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 (so disableLogging() silences them all), and a new resetLogging() clears an element's or type's own level.

Earlier releases: 3.0.0-rc01, 2.6.0-rc03, 2.6.0-rc02, CHANGELOG.

Install

npm install @keenmate/web-multiselect

Quick start

Declarative — 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).

Responsive rules

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 is desktop at any width.
  • breakpoint — the window width bucket (768 / 1024px lines, --base-breakpoint-*): a narrowed desktop window is mobile below 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.

Logging

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.

Editor IntelliSense

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.json via the web-types field in package.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.customData powers tag/attribute completion on <web-multiselect>; css.customData powers completion for the --ms-* theming variables. Reload the window after adding them.

HTML Injection (XSS) Notice

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.

Browser support

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.

Development

# 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            # both

Code structure

Follows 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, not HTMLElement directly. Core's BlissElement resolves to HTMLElement in the browser and to a stub class under SSR (typeof HTMLElement === 'undefined'), so importing the module in Node doesn't throw. A literal grep "extends HTMLElement" structure check will not match here by design.
  • src/vite-env.d.ts is a standard Vite ambient-types file, not part of the four-layer model.

License

MIT — see LICENSE.

Built with BlissFramework

Follows the BlissFramework component guidelines for structure, theming, color-scheme, and accessibility. Per-check verifications run via /validate-web-component.

Credits

Created by Keenmate as part of the Pure Admin design system.

About

A modern, framework-agnostic multi-select dropdown component built as a web component. Features RTL language support, async search, flexible data handling, form integration, multiple display modes, and extensive SCSS customization.

Topics

Resources

Accessibility

Stars

2 stars

Watchers

1 watching

Forks

Contributors

Languages