On this page
Combobox
Headless, unstyled single-select input: typing searches the options and choosing one keeps its value. Focus stays on the input while the arrow keys move a virtual highlight. Given items, it filters them by label and shows Empty when none match.
Use for
- the base for a styled select with search
- picking one value from a long list by typing
- a search field inside a popover that picks one value
Practices
| Guidance | Practice |
|---|---|
| Don’t | Use the primitive in a feature. Use the styled Combobox from src/components/combobox instead. |
| Do | Pass items and itemToStringLabel on the root, render options through Combobox.Collection, and annotate its children parameter with the item type. |
| Do | Keep Combobox.Empty mounted, so screen readers announce the message when it appears. |
| Do | Pass a localized aria-label to Combobox.Trigger, and to Combobox.Clear, which defaults to an English Clear. |
| Do | Pass defaultInputValue when an initial selection has a label that differs from its value. |
| Do | For search inside another popup, pass inline, render Combobox.List, and bind open to the outer popup. |
| Don’t | Pass id to an option or the list. The primitive owns them to wire the ARIA pairing. |
API reference
Combobox.Root
Holds the search text, the selected value and the open state. Renders no element. Closing restores the selected label in the input; clearing the input clears the selection.
| Prop | Type | Description |
|---|---|---|
items | readonly Item[] | Every option item. Collection renders the ones whose label contains the search text. |
itemToStringLabel | (item: Item) => string | The label items are searched by. Required with items. |
value | string | null | The selected value, or null for none, when controlled. |
defaultValue | string | null | The selected value on mount, when uncontrolled.Default: null |
onValueChange | (value: string | null) => void | Called with the selected value, or null when cleared. |
inputValue | string | The search text, when controlled. |
defaultInputValue | string | The search text on mount, when uncontrolled.Default: '' |
onInputValueChange | (value: string) => void | Called with the new search text. |
open | boolean | Whether the popup is open, when controlled. |
defaultOpen | boolean | Whether the popup is open on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
placement | Placement | Floating UI placement of the positioner.Default: 'bottom-start' |
sideOffset | number | Gap in px between the anchor and the positioner.Default: 4 |
inline | boolean | A search input inside another surface. Selecting clears the search instead of showing the label. |
openOnInputClick | boolean | Opens the popup when the input is clicked. No effect with inline. |
Combobox.Input
An input with aria-autocomplete="list". Typing opens the popup and highlights the first option; Enter selects the highlighted one. Carries data-open or data-closed.
Combobox.InputGroup
A div around the input and its buttons. The popup anchors to it, and a press inside it does not close the popup.
Combobox.Trigger
A button, out of the tab order, that toggles the popup and keeps focus on the input. Carries aria-expanded, aria-haspopup="listbox", and data-open or data-closed.
Combobox.Clear
A button, out of the tab order, that clears the search and selection and focuses the input. Renders only while there is text or a selection.
Combobox.Portal
Portals its children while the popup is mounted.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | null | React.RefObject<HTMLElement | null> | The element to portal into. |
Combobox.Positioner
The floating div, matched to the anchor width and capped at the available height. Carries data-side. Closes on Escape or an outside press.
| Prop | Type | Description |
|---|---|---|
anchor | HTMLElement | null | The element to position against.Default: the `InputGroup`, then the input |
Combobox.Popup
Wraps the options with transition attributes. Its children stay frozen while it closes, so the list does not change mid-exit.
Combobox.List
An inline listbox, used in place of Positioner and Popup inside another surface. Escape and outside presses pass to that surface.
Combobox.Collection
Renders the root items that match the search. Renders all of them when the input shows the selected label.
| Prop | Type | Description |
|---|---|---|
children | (item: Item) => ReactNode | Renders one item. Annotate the parameter with the item type. |
Combobox.Option
One role="option". Carries data-selected, data-active while highlighted, and data-disabled. A click selects it and returns focus to the input.
| Prop | Type | Description |
|---|---|---|
value | string | The value passed to onValueChange. |
label | string | The text shown in the input once selected.Default: `value` |
disabled | boolean | Skips the option on Enter and ignores clicks. |
Combobox.OptionIndicator
An aria-hidden span that renders only inside the selected option, such as a check mark.
Combobox.Empty
A polite role="status" region that shows its children only when no items match. Without items on the root it always shows them.
Combobox.Arrow
An optional svg arrow pointing at the anchor, from Floating UI. Carries data-side.
Examples
Search a list
<Combobox.Root items={fruits} itemToStringLabel={fruit => fruit}>
<Combobox.InputGroup>
<Combobox.Input aria-label='Fruit' />
<Combobox.Trigger aria-label='Show fruits' />
</Combobox.InputGroup>
<Combobox.Positioner>
<Combobox.Popup>
<Combobox.Empty>No fruit found</Combobox.Empty>
<Combobox.Collection>
{(fruit: string) => (
<Combobox.Option key={fruit} value={fruit}>
{fruit}
<Combobox.OptionIndicator>✓</Combobox.OptionIndicator>
</Combobox.Option>
)}
</Combobox.Collection>
</Combobox.Popup>
</Combobox.Positioner>
</Combobox.Root>