Skip to content
TrademarkTrademark
Docs
Form Controls

Combobox

Updated: November 19, 2026
View on GitHub

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.

When to use Combobox

  • 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.

Options

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.

Controlled

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.

Filtering

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.

Empty state

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.

Server results

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.

Accessibility

  • 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: "…" }}.

API reference

Combobox also takes the props of Input (id, label, placeholder, description, errorMessage, prefix, suffix and the rest), except onChange, onSelect and children.

Prop
Type
Default
Description
optionsComboboxOption[]requiredThe suggestions. Typing filters them unless filter is false.
valuestringThe field's text, controlled.
defaultValuestring""The starting text when value is left out.
onValueChange(value: string) => voidCalled with the text on every keystroke and every pick.
onOptionSelect(option: ComboboxOption) => voidCalled with the whole option when a suggestion is picked.
openbooleanWhether the list is open, controlled.
defaultOpenbooleanfalseWhether the list starts open, when open is left out.
onOpenChange(open: boolean) => voidCalled on every open and close.
filter((option: ComboboxOption, query: string) => boolean) | falsecontains, ignoring caseWhich suggestions match the text. false shows options as given.
loadingbooleanfalseShows a spinner row in the list while suggestions are on their way.
emptyStateReactNodeShown in the list when the text matches nothing. Left out, the list closes.
placementPlacementWhich side the list opens on, such as "bottom-start".
labels{ loading?: string }{ loading: "Loading…" }The Combobox's own words, for a translated interface.
fillWidthbooleantrueMatch the parent's width.
minHeightnumber | CSSUnitThe list's least height. From Dropdown.
minWidthnumber | CSSUnitThe list's least width. From Dropdown.
maxWidthnumber | CSSUnitThe list's greatest width. From Dropdown.

ComboboxOption

An Option's props without selected, highlighted, onClick and href.

Field
Type
Description
valuestringRequired. The option's key, and its text when label is not a string.
labelReactNodeWhat the option shows. A string label is the text a pick puts in the field.
descriptionReactNodeA second line under the label.
prefixReactNodeShown before the label, such as an avatar or an icon.
suffixReactNodeShown after the label.
toneToneThe option's palette.
dangerbooleanDraws the option in the danger look.
disabledbooleanShown but not pickable. The arrow keys skip it.
Edit this page on GitHub