Forms
Combobox
Pick one option from a list you can filter by typing. Only listed options are valid.
Live example
Type to filter, or use the arrow keys.
- Isla Calandra
- Lumen City
- Mirrow Peaks
- Port Everly
- Sunfold Bay
- Tamsin Isles
- Valmora Coast
- Kestrel Lakes
Selected value: lumen-city
Usage
<Combobox
label="Trip type"
options={[{ value: 'beach', label: 'Beach' }, { value: 'city', label: 'City' }]}
value={type}
onChange={setType}
/>Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | none | Visible label, also names the listbox. |
options | ComboboxOption[] | none | value, label, optional description and disabled. |
value? | string | null | none | Controlled selected value. |
defaultValue? | string | null | null | Uncontrolled initial value. |
onChange? | (value: string | null) => void | none | Called on selection, or with null when cleared. |
error? | string | none | Error message tied to the input. |
emptyMessage? | string | 'No matches' | Shown and announced when the filter matches nothing. |
required? | boolean | none | Adds aria-required and the visible marker. |
Do and don't
Do
- Use for lists longer than about seven options.
- Keep option labels short and distinct at the start.
Don't
- Use for two or three options; use RadioGroup.
- Accept free text silently; this component reverts to the last valid choice.
Accessibility
- Input has role combobox with aria-expanded, aria-controls and aria-autocomplete="list".
- Focus stays in the input. The active option is exposed with aria-activedescendant.
- The number of matching options is announced in a polite live region as you type.
Keyboard
| Keys | Action |
|---|---|
| Down Arrow | Opens the list, or moves to the next option |
| Up Arrow | Moves to the previous option |
| Alt + Down Arrow | Opens the list without moving |
| Enter | Selects the active option and closes |
| Escape | Closes the list; pressed again, clears the value |
| Tab | Closes the list and keeps the current value |