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.
Import
Section titled “Import”<script> import Combobox from "@invisible-ui/svelte/Combobox.svelte";</script><script setup> import { Combobox } from "@invisible-ui/vue";</script>import { Combobox } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-combobox></ds-combobox>Filter versus value
Section titled “Filter versus value”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.
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible name for the control. |
hideLabel | boolean | false | Visually hide the label while keeping it as the accessible name. The label text is always required. |
items * | (ComboboxItem & { icon?: string })[] | — | Options: { value, label?, disabled? }. |
value | string | null | null | Selected value. |
searchable | boolean | true | With 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. |
placeholder | string | undefined | undefined | Input placeholder. |
disabled | boolean | false | Disable the control. |
clearLabel | string | undefined | undefined | Accessible label for the clear button. |
emptyText | string | undefined | undefined | Shown when nothing matches. |
name | string | undefined | undefined | Form field name — the selected option's value is submitted under it (via a hidden input). |
onValueChange | ((value: string | null) => void) | undefined | undefined | Called when the selection changes. |
onInputValueChange | ((text: string) => void) | undefined | undefined | Called when the input text changes. |
icon | Snippet | undefined | undefined | Leading icon of a select-only combobox (searchable={false}). Defaults to the selected option's icon. |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible name for the control. |
hideLabel | boolean | false | Visually hide the label while keeping it as the accessible name. The label text is always required. |
items * | ComboboxOption[] | — | Options. Each may carry a leading icon; with the search hidden, the control mirrors the selected option's icon. |
modelValue | string | null | undefined | v-model value; takes precedence over value when bound. |
value | string | null | null | Selected value. null for none. |
searchable | boolean | true | With searchable: false the 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, wrap fits the longest option, fill takes 100% of the container. |
placeholder | string | undefined | Input placeholder. Defaults to the catalog's "Search…". |
disabled | boolean | false | |
clearLabel | string | undefined | Clear button accessible name. Defaults to the catalog's "Clear". |
emptyText | string | undefined | Text shown when no option matches. Defaults to the catalog's "No results". |
name | string | undefined | Form field name; the selected option's value is submitted under it. |
onValueChange | (value: string | null) => void | undefined | |
onInputValueChange | (text: string) => void | undefined |
| Event | Payload |
|---|---|
update:modelValue | value: string | null |
Slots: icon.
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible name for the control. |
hideLabel | boolean | false | Visually hide the label while keeping it as the accessible name. The label text is always required. |
items * | ComboboxOption[] | — | Options. Each may carry a leading icon; with the search hidden, the control mirrors the selected option's icon. |
value | string | null | null | |
searchable | boolean | true | With searchable={false} the 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, wrap fits the longest option, fill takes 100% of the container. |
placeholder | string | — | Input placeholder. Defaults to the catalog's "Search…". |
disabled | boolean | false | |
clearLabel | string | — | Clear button accessible name. Defaults to the catalog's "Clear". |
emptyText | string | — | Text shown when no option matches. Defaults to the catalog's "No results". |
name | string | — | Form field name — the selected option's value is submitted under it. |
onValueChange | (value: string | null) => void | — | |
onInputValueChange | (text: string) => void | — | |
icon | ReactNode | — | Leading icon shown when searchable={false} and no option icon applies. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | |
hide-label | yes | |
value | yes | |
searchable | yes | |
width | yes | wrap|fill|fixed |
placeholder | yes | |
disabled | yes | |
clear-label | yes | |
empty-text | yes | |
name | yes | submits via a hidden input |
description | yes | |
error | yes |
Reactive attributes re-render the element when they change after the first render.
Emits: change (detail.value), input-change (detail.value).
Accessibility
Section titled “Accessibility”- The input is
role="combobox"witharia-autocomplete="list",aria-expandedandaria-controls; the popup isrole="listbox"ofrole="option"s. DOM focus stays on the input while you type and choose; the highlight moves viaaria-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’sfilteroption. - 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. Withsearchable={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.
Example
Section titled “Example”<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).