Combobox is an Input with a list of suggestions under it: a city, a tag, a client's name, a model. Typing filters the list, and picking a suggestion fills in the field. Unlike Select, the person can also keep what they typed, so free text is a valid answer.
- Use Combobox when the answer can be anything, and a few common answers save typing.
- Use Select when the answer must be one of the options, such as a role or a timezone. A searchable Select filters a long list but still only accepts what is in it.
- Use TagInput when the field holds several values.
Each option takes the same fields as an Option: value, label, description, prefix, suffix, tone, danger and disabled. A pick puts the option's text in the field: its label when that is a string, otherwise its value. Arrow keys skip disabled options.
value and onValueChange hold the field's text, and onValueChange runs on every keystroke and every pick. onOptionSelect runs only on a pick, with the whole option, so you can tell a picked suggestion from typed text. open, defaultOpen and onOpenChange do the same for the list.
By default, an option matches when its text contains what was typed, ignoring case. filter takes your own test, called with each option and the current text.
When the text matches nothing, the list closes, since free text is still a valid answer. Pass emptyState to show a message in the list instead.
For suggestions that come from a search on the server, pass filter={false} so the Combobox shows the options as given, set loading while a request is out, and pass the options the server sent for the current text. While loading is set, the list shows a spinner row with the text from labels.loading.
- The field has role="combobox" with aria-autocomplete="list", and aria-expanded, aria-controls and aria-activedescendant point at the list and its active option. The list is a listbox, named after the field's aria-label, label or placeholder.
- Focus stays in the field. The Down and Up arrows open the list and move through the suggestions, wrapping round. Enter takes the active suggestion, and does not submit the form when it does. With no active suggestion, Enter keeps the typed text.
- Escape closes the list. A second Escape clears the text. Inside a Dialog, Escape closes the list only, not the dialog.
- Tab closes the list and moves on.
- While loading, the list is marked aria-busy and the loading row is a status, so screen readers announce it. Translate its text with labels={{ loading: "…" }}.
Combobox also takes the props of Input (id, label, placeholder, description, errorMessage, prefix, suffix and the rest), except onChange, onSelect and children.
An Option's props without selected, highlighted, onClick and href.