Skip to content
Mosaic
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 inline and Combobox.List

Practices

GuidancePractice
DoPass items and itemToStringLabel to Combobox.Root and render options with Combobox.Collection, so the search filters them.
DoKeep Combobox.Empty mounted, so screen readers announce it when nothing matches.
DoWrap the input and its buttons in Combobox.InputGroup, so the popup lines up with the whole group.
DoPass defaultInputValue when an initial selection's label differs from its value.
DoGive 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.

PropTypeDescription
itemsreadonly Item[]Every option's item. Collection renders those that match the search.
itemToStringLabel(item: Item) => stringThe label an item is searched by.
valuestring | nullThe selected value, when controlled.
defaultValuestring | nullThe selected value on mount.Default: null
onValueChange(value: string | null) => voidCalled with the new value, or null when cleared.
inputValuestringThe search text, when controlled.
defaultInputValuestringThe search text on mount.Default: ''
onInputValueChange(value: string) => voidCalled with the new search text.
openbooleanWhether the popup is open, when controlled.
defaultOpenbooleanWhether the popup is open on mount.Default: false
onOpenChange(open: boolean) => voidCalled 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'
sideOffsetnumberGap between the anchor and the popup, in px.Default: 8
inlinebooleanSearch inside another surface. Bind open to that surface and use Combobox.List.
openOnInputClickbooleanOpens 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.

PropTypeDescription
children(item: Item) => ReactNodeRenders 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

PropTypeDescription
sizeComboboxSizesm, md or lg. Ignored inside an input group.Default: 'md'
variantInputVariantThe 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

PropTypeDescription
anchorReact.ComponentPropsWithoutRef<typeof HeadlessCombobox.Positioner>['anchor']Positions the popup against this instead of the input group or input.
portalRootReact.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

PropTypeDescription
valuestringThe value selected when the option is chosen.
labelstringThe text typeahead matches.Default: `value`
disabledbooleanMakes 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

TSX
<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>