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
| Guidance | Practice |
|---|---|
| Do | Filter the options yourself from inputValue. The primitive does not filter. |
| Do | Inside 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’t | Pass id to an option or the list. The primitive owns them to wire the ARIA pairing. |
| Don’t | Use 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.
| Prop | Type | Description |
|---|---|---|
inputValue | string | The input text, when controlled. |
defaultInputValue | string | The input text on mount, when uncontrolled.Default: '' |
onInputValueChange | (value: string) => void | Called with the new input text, including the label of a selected option. |
value | string | The selected option value, when controlled. |
defaultValue | string | The selected option value on mount, when uncontrolled. |
onValueChange | (value: string) => void | Called with the value of the selected option. |
open | boolean | Whether the list is open, when controlled. |
defaultOpen | boolean | Whether the list 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 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.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | 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.
| Prop | Type | Description |
|---|---|---|
value | string | The value passed to onValueChange. |
label | string | The text put in the input on selection.Default: `value` |
disabled | boolean | Skips 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
<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>