Multi Select
A labelled, editable input that filters a multiselectable listbox; the
chosen values render as removable tags in a labelled list. A sibling of
Combobox with its own contract: values is an
ordered, unique, controlled string[] with onValuesChange. Free-form
values, reordering, drag and drop and async fetching are out of scope.
Import
Section titled “Import”<script> import MultiSelect from "@invisible-ui/svelte/MultiSelect.svelte";</script><script setup> import { MultiSelect } from "@invisible-ui/vue";</script>import { MultiSelect } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-multi-select></ds-multi-select>Props (selected)
Section titled “Props (selected)”| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible, visible label (required). |
items * | MultiSelectItem[] | — | Ordered list of all options. |
values | string[] | [] | The selected values (controlled). Replace the array; do not mutate it. |
onValuesChange | ((values: string[]) => void) | undefined | undefined | Called with the next values after a user action. |
onInputValueChange | ((text: string) => void) | undefined | undefined | |
onOpenChange | ((open: boolean) => void) | undefined | undefined | |
placeholder | string | undefined | undefined | Input placeholder. Defaults to the i18n catalog's "Search…". |
disabled | boolean | false | |
readOnly | boolean | false | Review-only: focus works, opening/adding/removing do not. |
max | number | undefined | undefined | Cap on additions; never removes existing values. |
removeOnBackspace | boolean | false | Opt in to Backspace removal from an empty input. |
name | string | undefined | undefined | Form field name; one hidden input per value is submitted under it. |
required | boolean | false | Expose aria-required on the input. Native constraint validation cannot cover hidden multi-value inputs; validation stays with the application. |
emptyText | string | undefined | undefined | Empty-result row text. Defaults to the i18n catalog's "No results". |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible, visible label (required). |
items * | MultiSelectItem[] | — | Ordered list of all options. |
values | string[] | () => [] | The selected values (controlled). Replace the array; do not mutate it. |
onValuesChange | (values: string[]) => void | undefined | Called with the next values after a user action. |
onInputValueChange | (text: string) => void | undefined | |
onOpenChange | (open: boolean) => void | undefined | |
placeholder | string | undefined | Input placeholder. Defaults to the catalog's "Search…". |
disabled | boolean | false | |
readOnly | boolean | false | Review-only: focus works, opening/adding/removing do not. |
max | number | undefined | Cap on additions; never removes existing values. |
removeOnBackspace | boolean | false | Opt in to Backspace removal from an empty input. |
name | string | undefined | Form field name; one hidden input per value is submitted under it. |
required | boolean | false | Expose aria-required on the input. Native constraint validation cannot cover hidden multi-value inputs; validation stays with the application. |
emptyText | string | undefined | Empty-result row text. Defaults to the catalog's "No results". |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible, visible label (required). |
items * | MultiSelectItem[] | — | Ordered list of all options. |
values | string[] | — | The selected values (controlled). Replace the array; do not mutate it. |
onValuesChange | (values: string[]) => void | — | Called with the next values after a user action. |
onInputValueChange | (text: string) => void | — | |
onOpenChange | (open: boolean) => void | — | |
placeholder | string | — | Input placeholder. Defaults to the catalog's "Search…". |
disabled | boolean | false | |
readOnly | boolean | false | Review-only: focus works, opening/adding/removing do not. |
max | number | — | Cap on additions; never removes existing values. |
removeOnBackspace | boolean | false | Opt in to Backspace removal from an empty input. |
name | string | — | Form field name; one hidden input per value is submitted under it. |
required | boolean | false | Expose aria-required on the input. Native constraint validation cannot cover hidden multi-value inputs; validation stays with the application. |
emptyText | string | — | Empty-result row text. Defaults to the catalog's "No results". |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | |
values | yes | |
placeholder | yes | |
disabled | yes | |
readonly | yes | |
max | yes | |
remove-on-backspace | yes | |
required | yes | |
empty-text | yes | |
name | yes | |
description | yes | |
error | yes |
Reactive attributes re-render the element when they change after the first render.
Emits: change (detail.values: string[]), input-change (detail.value).
Behavior
Section titled “Behavior”- Enter adds the highlighted option and keeps the popup open for another
choice; a selected option stays listed with
aria-selected="true", and selecting it again is a no-op. Escape closes without moving focus. - A value whose item disappears from
itemsstays selected and shows its raw value as the tag label; it is never discarded silently. maxblocks further additions but never removes existing values.disabledblocks everything;readOnlypermits focus and review only.- Backspace edits text. Only with
removeOnBackspaceand an empty input does one Backspace remove the last removable value (disabled values are immune). - Removing a tag through its remove button moves focus to the next remove button, else the previous one, else the input.
With name, one hidden input per selected value is submitted under the same
name, in selection order: read it with FormData.getAll(name). An empty
selection contributes no entry. Native required constraint validation cannot
work over hidden inputs, so required only exposes aria-required;
validation belongs to Field or application state.
Accessibility
Section titled “Accessibility”- The input is a labelled
role="combobox"over aaria-multiselectablelistbox; DOM focus stays on the input and the highlighted option travels througharia-activedescendant. - Tags form a labelled selected-values list (never option semantics); every
remove button is an ordinary Tab stop named
Remove <label>with a visible focus indication and a WCAG 2.5.8 target. - Tags and the input wrap without clipping at 320 CSS pixels, with long labels, localization growth and RTL.
Framework mapping
Section titled “Framework mapping”The behavior contract is identical everywhere; only the syntax differs.
- React:
MultiSelectwith the same props as Svelte/Vue (values/onValuesChange). - Elements:
<ds-multi-select>in light DOM with<option>children or theitemsproperty; the selection is thevaluesproperty (string array) mirrored as a space-separatedvaluesattribute; events arechange(detail.values) andinput-change;readonlyandremove-on-backspaceare attributes. - Reflex:
multi_select(...)wraps the React component; snake_case props (remove_on_backspace,read_only) reach React camelCased.
Themeable via --ds-multi-select-*.