Skip to content
Mosaic
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

GuidancePractice
Don’tUse the primitive in a feature. Use the styled Combobox from src/components/combobox instead.
DoPass items and itemToStringLabel on the root, render options through Combobox.Collection, and annotate its children parameter with the item type.
DoKeep Combobox.Empty mounted, so screen readers announce the message when it appears.
DoPass a localized aria-label to Combobox.Trigger, and to Combobox.Clear, which defaults to an English Clear.
DoPass defaultInputValue when an initial selection has a label that differs from its value.
DoFor search inside another popup, pass inline, render Combobox.List, and bind open to the outer popup.
Don’tPass 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.

PropTypeDescription
itemsreadonly Item[]Every option item. Collection renders the ones whose label contains the search text.
itemToStringLabel(item: Item) => stringThe label items are searched by. Required with items.
valuestring | nullThe selected value, or null for none, when controlled.
defaultValuestring | nullThe selected value on mount, when uncontrolled.Default: null
onValueChange(value: string | null) => voidCalled with the selected value, or null when cleared.
inputValuestringThe search text, when controlled.
defaultInputValuestringThe search text on mount, when uncontrolled.Default: ''
onInputValueChange(value: string) => voidCalled with the new search text.
openbooleanWhether the popup is open, when controlled.
defaultOpenbooleanWhether the popup is open on mount, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
placementPlacementFloating UI placement of the positioner.Default: 'bottom-start'
sideOffsetnumberGap in px between the anchor and the positioner.Default: 4
inlinebooleanA search input inside another surface. Selecting clears the search instead of showing the label.
openOnInputClickbooleanOpens 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.

PropTypeDescription
rootHTMLElement | 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.

PropTypeDescription
anchorHTMLElement | nullThe 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.

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

PropTypeDescription
valuestringThe value passed to onValueChange.
labelstringThe text shown in the input once selected.Default: `value`
disabledbooleanSkips 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

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