Combobox
Choose one collection item through an editable search input.
Anatomy#
Combobox renders the portaled popup internally; the popup names are style slots, not attached parts.
Usage#
Use Combobox when users should type to find one item in a collection. Use Select for a non-editable choice, MultiSelect for several collection values, or BaseSelect to compose the listbox yourself.
String items#
Pass strings when the label and value are identical. You can mix strings and objects at the root or inside a group. Whitespace is preserved, and an empty string is a valid value.
String items are converted to the same item shape used by callbacks: 'Apple' becomes
{ value: 'Apple', label: 'Apple' }. Object items keep their identity and custom fields.
ComboboxT.NormalizedItem<TItem> is the callback item type. Item values must be unique. When two
items share a value, the first one wins (including a string that collides with an object), and
development builds log an error.
Value and query#
Pair value with onValueChange for controlled selection, or use defaultValue for an initial
uncontrolled choice. value={undefined} keeps the selection uncontrolled; value={null} keeps it
controlled and empty. onValueChange receives null when the selection is cleared, and inside a
form field, clearing writes null.
While open, the input displays the query; while closed, it displays the selected item label.
Query text is never committed as a value, and filtering never changes the selection. Use value /
onValueChange for selection and searchValue / onSearchValueChange for query text. The query
resets to '' when the popup finishes closing and after a native form reset; in controlled mode,
onSearchValueChange('') reports these resets and you decide whether to apply them.
Clear and loading#
clearable shows a clear button while there is a selected value or query text. Clearing resets the
selection and the query, calls onValueChange(null) if a value existed, then onClear, and returns
focus to the input. loading replaces the toggle icon with loadingIcon and disables the toggle
button; typing and the clear button keep working.
Pointer opening#
By default, clicking inside the control focuses the input without opening the popup. The trailing
chevron button toggles the popup, and typing non-blank text or pressing ArrowDown opens it. Set
openOnControlClick to open the popup on any click on the control outside its buttons.
Keyboard interaction#
Focus stays in the input; the highlighted option is exposed through aria-activedescendant.
| Key | Behavior |
|---|---|
| ArrowDown / ArrowUp | Open the popup and move the highlight through enabled options |
| PageUp / PageDown | Move the highlight by one page of options while open |
| Enter | Open the popup, or commit the highlighted option while open |
| Escape | Close the popup; with the popup closed and clearable, clear the value and query |
| Backspace / Delete | With an empty input and clearable, clear the value |
| Tab | Close the popup and move focus on |
| Home / End | Move the text cursor; they never move the highlight |
Virtualization#
Pass a virtualizer from createListVirtualizer when rendering the full collection makes opening
or scrolling slow. Type it over ComboboxT.Row. Read the Virtualization guide
for setup, row measurement, stable keys, and keyboard navigation.
Examples#
Search a framework#
Filter a local collection as the user types. clearable removes the committed value and the
query text.
Pick an issue status#
Put icon and description on each item when the option needs a status mark and secondary line.
Assign a teammate#
Search people by name; each item’s description shows the email and role. The default filter
matches the label only. Set openOnControlClick to open the list as soon as the user clicks the
control.
Match by contains or prefix#
filterMethod defaults to 'contains', which matches the query anywhere in the label. Set
'startsWith' or 'endsWith' to match only at that end of the label, or pass a predicate for
custom matching.
Search remote repositories#
Drive searchValue, onSearchValueChange, and loading from a debounced request. Set
filterMethod={false} when the server already returns the matched items.
Browse grouped technologies#
Organize options into type: 'group' entries. Use emptyRender to customize the empty state when
the query has no matches.
Search a large collection#
Pass a createListVirtualizer instance as virtualizer when rendering every row on open is slow.
Bind a searchable field to a form#
Use form.Field from createForm when the selected value needs schema validation and error
display. required is satisfied by any selected item, including a disabled one. In that case the
combobox passes constraint validation but submits no value, as a native <select> does with a
disabled selected option.
Keep the query separate from the committed value#
value is the selected item. searchValue is the text in the field. Reset both when the page
clears the picker.
Open the list from the whole field#
By default, typing and the chevron button open the popup. Set openOnControlClick when a click
anywhere on the control should open it, as in an assignee picker.
Accept string labels or mixed items#
Pass a string array when the label is the value. Mix strings, item objects, and type: 'group'
entries in one items list.
API Reference#
Attributes#
data-closeddata-disableddata-editabledata-expandeddata-invaliddata-readonlydata-requireddata-sidedata-highlighteddata-selecteddata-loadingProps#
Renders a <div> element by default.