Skip to content

Combobox

An editable autocomplete (WAI-ARIA editable combobox): a text input paired with a filtered listbox. Unlike Select (a native <select> with plain-text options), the user types to filter.

With searchable={false} it becomes the advanced select: a read-only trigger that always lists every option — styled popup, per-option icons (the control mirrors the selected one) and the width modes (wrap / fill / fixed), for the cases the native Select can’t render.

<script>
import Combobox from "@invisible-ui/svelte/Combobox.svelte";
</script>

The text you type is a filter, not a value: this combobox only takes values from its list. So leaving the field settles it — the list closes and the text goes back to the selected option’s label, or to empty when nothing is selected. Escape does the same in one keystroke. Nothing is reported as chosen that was not chosen, and a form never carries a label that matches no value.

A Search Dialog works the other way round: its text is a query the user wrote, so it is kept.

PropTypeDefaultDescription
label *string—Accessible name for the control.
hideLabelbooleanfalseVisually hide the label while keeping it as the accessible name. The label text is always required.
items *(ComboboxItem & { icon?: string })[]—Options: { value, label?, disabled? }.
valuestring | nullnullSelected value.
searchablebooleantrueWith searchable={false} the text input becomes read-only and the list always shows every option — a select-only combobox: the advanced Select (styled popup, per-option icons) without the autocomplete.
width"wrap" | "fill" | "fixed""fixed"Width behaviour: fixed (default) uses --ds-combobox-width (16rem), wrap fits the longest option, fill takes 100% of the container.
placeholderstring | undefinedundefinedInput placeholder.
disabledbooleanfalseDisable the control.
clearLabelstring | undefinedundefinedAccessible label for the clear button.
emptyTextstring | undefinedundefinedShown when nothing matches.
namestring | undefinedundefinedForm field name — the selected option's value is submitted under it (via a hidden input).
onValueChange((value: string | null) => void) | undefinedundefinedCalled when the selection changes.
onInputValueChange((text: string) => void) | undefinedundefinedCalled when the input text changes.
iconSnippet | undefinedundefinedLeading icon of a select-only combobox (searchable={false}). Defaults to the selected option's icon.
  • The input is role="combobox" with aria-autocomplete="list", aria-expanded and aria-controls; the popup is role="listbox" of role="option"s. DOM focus stays on the input while you type and choose; the highlight moves via aria-activedescendant.
  • Typing filters; Arrow Up/Down move the highlight, Enter selects (filling the input), Escape closes. Filtering, positioning (flip/shift) and keeping the active option in view are handled by the adapter. Provide your own matcher via the headless createCombobox’s filter option.
  • The clear control is a real <button>: Tab reaches it only while there is something to clear, and Enter, Space or a pointer press empties the control and returns focus to the input. With searchable={false} this is the keyboard’s only way to empty a read-only control. What a screen reader’s own activation does is not verified before the manual accessibility session.
<Combobox
label="Fruit"
items={[{ value: "apple", label: "Apple" }, { value: "pear", label: "Pear" }]}
onValueChange={(v) => (fruit = v)}
/>

Themeable via --ds-combobox-* (and the shared --ds-select-* listbox tokens).