# 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

- 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 | Default | Description |
| --- | --- | --- | --- |
| `inputValue` | `string` |  | The input text, when controlled. |
| `defaultInputValue` | `string` | `''` | The input text on mount, when uncontrolled. |
| `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` | `false` | Whether the list is open on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `placement` | `Placement` | `'bottom-start'` | Floating UI placement of the positioner. |
| `sideOffset` | `number` | `4` | Gap in px between the input and the positioner. |

### 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 | Default | 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 | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The value passed to `onValueChange`. |
| `label` | `string` | `` `value` `` | The text put in the input on selection. |
| `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

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

## Related

- [Combobox](/docs/components/combobox.md)
- [Select](/docs/components/select.md)
- [Popover](/docs/components/popover.md)
