Skip to content
Mosaic
On this page

Autocomplete

Headless, unstyled text input with a list of suggestions the caller filters. Focus stays on the input while the arrow keys move a virtual highlight through the options via aria-activedescendant. Selecting an option sets the input text to its label and closes the list.

Use for

  • a search input with suggestions
  • typing to narrow a list of options
  • a filterable list inside a popover or dialog

Practices

GuidancePractice
DoFilter the options yourself from inputValue. The primitive does not filter.
DoInside a popover or dialog, render Autocomplete.List in place of Positioner and Popup, and let the outer surface own visibility, Escape and outside clicks.
Don’tPass id to an option or the list. The primitive owns them to wire the ARIA pairing.
Don’tUse it to pick from a fixed list. Use Select, or Combobox to pick with search.

API reference

Autocomplete.Root

Holds the input text, the selected value and the open state. Renders no element. Typing a non-empty string opens the list and highlights the first option; clearing the input closes it.

PropTypeDescription
inputValuestringThe input text, when controlled.
defaultInputValuestringThe input text on mount, when uncontrolled.Default: ''
onInputValueChange(value: string) => voidCalled with the new input text, including the label of a selected option.
valuestringThe selected option value, when controlled.
defaultValuestringThe selected option value on mount, when uncontrolled.
onValueChange(value: string) => voidCalled with the value of the selected option.
openbooleanWhether the list is open, when controlled.
defaultOpenbooleanWhether the list 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 input and the positioner.Default: 4

Autocomplete.Input

An input with aria-autocomplete="list". Enter selects the highlighted option. Carries data-open or data-closed.

Autocomplete.Portal

Portals its children while the list is mounted.

PropTypeDescription
rootHTMLElement | null | React.RefObject<HTMLElement | null>The element to portal into.

Autocomplete.Positioner

The floating div placed against the input, matched to its width and capped at the available height. Carries data-side. Keeps focus on the input and closes on Escape or an outside click.

Autocomplete.Popup

Wraps the options with transition attributes. Its children stay frozen while it closes, so the list does not change mid-exit.

Autocomplete.List

An inline listbox, used in place of Positioner and Popup inside another floating surface. Escape and outside clicks pass to that surface.

Autocomplete.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 put in the input on selection.Default: `value`
disabledbooleanSkips the option on Enter and ignores clicks.

Autocomplete.Arrow

An optional svg arrow pointing at the input, from Floating UI. Carries data-side.

Examples

A filtered list

TSX
<Autocomplete.Root inputValue={query} onInputValueChange={setQuery}>
  <Autocomplete.Input placeholder='Search' />
  <Autocomplete.Positioner>
    <Autocomplete.Popup>
      {matches.map(item => (
        <Autocomplete.Option key={item.id} value={item.id} label={item.name}>
          {item.name}
        </Autocomplete.Option>
      ))}
    </Autocomplete.Popup>
  </Autocomplete.Positioner>
</Autocomplete.Root>