Combobox
A text field that suggests options as the user types; choosing one fills the field.
Stability: experimental
Props
| Prop | Type | Default | Means |
|---|---|---|---|
label | string | The label above the field, and its accessible name. | |
options | string[] | Every option; those containing what was typed are suggested, six at most. | |
value | string | bindable("") | The text. Bind it with bind:value={name}. |
placeholder | string | Hint text while empty. | |
onChoose | (option: string) => void | Runs when a suggestion is chosen. |
States
| State | Looks like |
|---|---|
empty | The field only. |
suggesting | A listbox of matching options under the field, on the overlay layer. |
Accessibility
| role | combobox (the field), with aria-expanded and aria-controls naming a listbox of options |
| name | The label prop; the listbox is "Suggestions for <label>". |
| focus | Typing keeps focus in the field while the suggestions show. Choosing one returns focus to the field; Tab from the field closes them and moves on. |
| keyboard | Typing filters the suggestions. ArrowDown moves to the first, ArrowUp to the last, and the arrows move between them; Enter and Space choose one; Escape closes them and leaves focus in the field, and the arrows open them again. |
| notes | On a phone the field hears no keys, so the suggestions are pressed; VoiceOver and TalkBack reach them in order after the field. |
Theme tokens
color.border color.surface color.ink shadow.md space.1 space.3 text.label text.body
Example
<Combobox label="City" options={cities} bind:value={city} />