On this page
Combobox
A styled single-select input that searches its options as the user types. Wraps the headless Combobox primitive; the popup portals and positions itself.
Use for
- picking one option from a long list by typing to search
- a country or language picker
- a search list inside another popup, with
inlineandCombobox.List
Practices
| Guidance | Practice |
|---|---|
| Do | Pass items and itemToStringLabel to Combobox.Root and render options with Combobox.Collection, so the search filters them. |
| Do | Keep Combobox.Empty mounted, so screen readers announce it when nothing matches. |
| Do | Wrap the input and its buttons in Combobox.InputGroup, so the popup lines up with the whole group. |
| Do | Pass defaultInputValue when an initial selection's label differs from its value. |
| Do | Give Combobox.Input and Combobox.Trigger a localized accessible name, and Combobox.Clear a localized aria-label. |
API reference
Combobox.Root
Holds the open state, the search text and the selected value. Clearing the input selects null. Renders no element.
| Prop | Type | Description |
|---|---|---|
items | readonly Item[] | Every option's item. Collection renders those that match the search. |
itemToStringLabel | (item: Item) => string | The label an item is searched by. |
value | string | null | The selected value, when controlled. |
defaultValue | string | null | The selected value on mount.Default: null |
onValueChange | (value: string | null) => void | Called with the new value, or null when cleared. |
inputValue | string | The search text, when controlled. |
defaultInputValue | string | The search text on mount.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.Default: false |
onOpenChange | (open: boolean) => void | Called when the popup opens or closes. |
placement | 'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | Popup placement.Default: 'bottom-start' |
sideOffset | number | Gap between the anchor and the popup, in px.Default: 8 |
inline | boolean | Search inside another surface. Bind open to that surface and use Combobox.List. |
openOnInputClick | boolean | Opens the popup when the input is clicked. No effect with inline.Default: true |
Combobox.Collection
Renders the root's items that match the search text, case-insensitively. Renders no element.
| Prop | Type | Description |
|---|---|---|
children | (item: Item) => ReactNode | Renders one item. Annotate the parameter with the item type. |
Combobox.InputGroup
An InputGroup.Root around the input and its buttons. The popup anchors to it, and pressing inside it keeps the popup open.
Combobox.Input
The search input, rendered as Input. Inside an input group it is ghost and takes the group size.
Slot: cl-combobox-input
| Prop | Type | Description |
|---|---|---|
size | ComboboxSize | sm, md or lg. Ignored inside an input group.Default: 'md' |
variant | InputVariant | The Input variant.Default: `ghost` in an input group, else `default` |
Combobox.Trigger
A Button that toggles the popup. Shows a chevron when given no children.
Slot: cl-combobox-trigger
Combobox.Clear
A Button that clears the search and the selection. Out of the tab order, with the default aria-label 'Clear'. Shows an X when given no children.
Slot: cl-combobox-clear
Combobox.Popup
The floating, scrollable listbox. Portals and positions itself; the positioner carries cl-combobox-positioner and the scroll box cl-combobox-viewport.
Slot: cl-combobox-popup
| Prop | Type | Description |
|---|---|---|
anchor | React.ComponentPropsWithoutRef<typeof HeadlessCombobox.Positioner>['anchor'] | Positions the popup against this instead of the input group or input. |
portalRoot | React.ComponentPropsWithoutRef<typeof HeadlessCombobox.Portal>['root'] | Where the popup portals.Default: `document.body` |
Combobox.List
A scrollable listbox in flow, for a combobox embedded in another surface. Turns on inline mode.
Slot: cl-combobox-list
Combobox.Option
One option.
Slot: cl-combobox-option
| Prop | Type | Description |
|---|---|---|
value | string | The value selected when the option is chosen. |
label | string | The text typeahead matches.Default: `value` |
disabled | boolean | Makes the option unselectable. |
Combobox.Media
A square leading column for an icon, flag or avatar, as a span.
Slot: cl-combobox-option-media
Combobox.Label
The option's name, as a span. Truncates to one line.
Slot: cl-combobox-option-label
Combobox.Detail
Secondary trailing text, such as a code or count. Stays whole while the label truncates.
Slot: cl-combobox-option-detail
Combobox.OptionIndicator
Shows on the selected option. A checkmark when given no children.
Slot: cl-combobox-option-indicator
Combobox.Empty
A polite role="status" region that shows its children only when nothing matches.
Slot: cl-combobox-empty
Examples
A searchable picker
<Combobox.Root items={countries} itemToStringLabel={country => country.name}>
<Combobox.InputGroup>
<Combobox.Input aria-label={m.country} />
<Combobox.Trigger aria-label={m.showCountries} />
</Combobox.InputGroup>
<Combobox.Popup>
<Combobox.Empty>{m.noResults}</Combobox.Empty>
<Combobox.Collection>
{(country: Country) => (
<Combobox.Option key={country.code} value={country.code} label={country.name}>
<Combobox.Label>{country.name}</Combobox.Label>
<Combobox.OptionIndicator />
</Combobox.Option>
)}
</Combobox.Collection>
</Combobox.Popup>
</Combobox.Root>