Installation

Barrel

// code example

Granular

// code example

When to use

Use Autocomplete when the input value can be free-form text and suggestions are optional hints. Use Combobox instead when the selected value must come from the predefined list.

Controlled

Pass value and onValueChange for controlled usage.

With Field

Add label, description, and required to enable the built-in Field wrapper.

Error State

Display validation errors with the error prop.

Grouped

Group items into categories using Autocomplete.Group and Autocomplete.GroupLabel.

Sizes

The size prop on Autocomplete.InputGroup supports four variants matching the Input component: xs, sm, base (default), and lg.

Custom Filtering

By default, Base UI filters items using a built-in string match. Pass a custom filter function for advanced logic such as fuzzy matching or object properties.

// Filter on a property of object items
<Autocomplete
  items={countries}
  filter={(item, query) =>
    item.label.toLowerCase().includes(query.toLowerCase())
  }
>
  ...
</Autocomplete>

// Disable filtering entirely (e.g. async search)
<Autocomplete items={results} filter={null}>
  ...
</Autocomplete>

API Reference

Autocomplete

Root component. Wraps all sub-components and manages state.

Autocomplete.InputGroup

Self-contained input wrapper that renders the text input, clear button, and dropdown trigger together.

Autocomplete.Content

Dropdown popup container. Wraps Portal, Positioner, and Popup.

Autocomplete.Item

Individual suggestion item in the list.

Additional Sub-components

• `Autocomplete.List` — scrollable list container with render prop
• `Autocomplete.Group` — groups items under a heading
• `Autocomplete.GroupLabel` — heading label for a group
• `Autocomplete.Collection` — item container within a group
• `Autocomplete.Separator` — horizontal divider between items