Skip to content

Multi Select

  • Grace Hopper
  • Ada Lovelace
  • Grace Hopper
  • Barbara Liskov
  • Alan Turing
  • Edsger Dijkstra
  • Katherine Johnson

Submitted: none

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.

<script>
import MultiSelect from "@invisible-ui/svelte/MultiSelect.svelte";
</script>
PropTypeDefaultDescription
label *string—Accessible, visible label (required).
items *MultiSelectItem[]—Ordered list of all options.
valuesstring[][]The selected values (controlled). Replace the array; do not mutate it.
onValuesChange((values: string[]) => void) | undefinedundefinedCalled with the next values after a user action.
onInputValueChange((text: string) => void) | undefinedundefined
onOpenChange((open: boolean) => void) | undefinedundefined
placeholderstring | undefinedundefinedInput placeholder. Defaults to the i18n catalog's "Search…".
disabledbooleanfalse
readOnlybooleanfalseReview-only: focus works, opening/adding/removing do not.
maxnumber | undefinedundefinedCap on additions; never removes existing values.
removeOnBackspacebooleanfalseOpt in to Backspace removal from an empty input.
namestring | undefinedundefinedForm field name; one hidden input per value is submitted under it.
requiredbooleanfalseExpose aria-required on the input. Native constraint validation cannot cover hidden multi-value inputs; validation stays with the application.
emptyTextstring | undefinedundefinedEmpty-result row text. Defaults to the i18n catalog's "No results".
  • 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 items stays selected and shows its raw value as the tag label; it is never discarded silently.
  • max blocks further additions but never removes existing values. disabled blocks everything; readOnly permits focus and review only.
  • Backspace edits text. Only with removeOnBackspace and 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.

  • The input is a labelled role="combobox" over a aria-multiselectable listbox; DOM focus stays on the input and the highlighted option travels through aria-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.

The behavior contract is identical everywhere; only the syntax differs.

  • React: MultiSelect with the same props as Svelte/Vue (values/onValuesChange).
  • Elements: <ds-multi-select> in light DOM with <option> children or the items property; the selection is the values property (string array) mirrored as a space-separated values attribute; events are change (detail.values) and input-change; readonly and remove-on-backspace are attributes.
  • Reflex: multi_select(...) wraps the React component; snake_case props (remove_on_backspace, read_only) reach React camelCased.

Themeable via --ds-multi-select-*.