Autocomplete

An input that suggests options as you type.

Usage guidelines

• Avoid when selection state is needed: Use Combobox instead of Autocomplete if the selection should be remembered and the input value cannot be custom. Unlike Combobox, Autocomplete's input can contain free-form text, as its suggestions only optionally autocomplete the text.
• Can be used for filterable command pickers: The input can be used as a filter for command items that perform an action when clicked when rendered inside the popup.
• Form controls must have an accessible name: It can be created using a <label> element or the Field component. See the forms guide.

Anatomy

Import the components and place them together:

import { Autocomplete } from '@base-ui/react/autocomplete';

<Autocomplete.Root>
  <Autocomplete.Input />
  <Autocomplete.Trigger />
  <Autocomplete.Icon />
  <Autocomplete.Clear />
  <Autocomplete.Value />

  <Autocomplete.Portal>
    <Autocomplete.Backdrop />
    <Autocomplete.Positioner>
      <Autocomplete.Popup>
        <Autocomplete.Arrow />

        <Autocomplete.Status />
        <Autocomplete.Empty />

        <Autocomplete.List>
          <Autocomplete.Row>
            <Autocomplete.Item />
          </Autocomplete.Row>

          <Autocomplete.Separator />

          <Autocomplete.Group>
            <Autocomplete.GroupLabel />
          </Autocomplete.Group>

          <Autocomplete.Collection />
        </Autocomplete.List>
      </Autocomplete.Popup>
    </Autocomplete.Positioner>
  </Autocomplete.Portal>
</Autocomplete.Root>;

TypeScript inference

Autocomplete infers the item type from the items prop passed to <Autocomplete.Root>. If using itemToStringValue, the value prop on the <Autocomplete.Item> must match the type of an item in the items array.

Examples

Async search

Load items asynchronously while typing and render custom status content.

Inline autocomplete

Autofill the input with the highlighted item while navigating with arrow keys using the mode prop. Accepts aria-autocomplete values list, both, inline, or none.

Grouped

Organize related options with <Autocomplete.Group> and <Autocomplete.GroupLabel> to add section headings inside the popup.

Groups are represented by an array of objects with an items property, which itself is an array of individual items for each group. An extra property, such as value, can be provided for the heading text when rendering the group label.

interface ProduceGroupItem {
  value: string;
  items: string[];
}

const groups: ProduceGroupItem[] = [
  {
    value: 'Fruits',
    items: ['Apple', 'Banana', 'Orange'],
  },
  {
    value: 'Vegetables',
    items: ['Carrot', 'Lettuce', 'Spinach'],
  },
];

Fuzzy matching

Use fuzzy matching to find relevant results even when the query doesn't exactly match the item text.

Limit results

Limit the number of visible items using the limit prop and guide users to refine their query using <Autocomplete.Status>.

Auto highlight

The first matching item can be automatically highlighted as the user types by specifying the autoHighlight prop on <Autocomplete.Root>. Set the prop's value to "always" if the highlight should always be present, such as when the list is rendered inline within a dialog.

The prop can be combined with the keepHighlight and highlightItemOnHover props to configure how the highlight behaves during mouse interactions.

Command palette

Use the autocomplete input to filter a list of command items that perform an action when clicked.

Grid layout

Display items in a grid layout, wrapping each row in <Autocomplete.Row> components.

Virtualized

Efficiently handle large datasets using a virtualization library like @tanstack/react-virtual.

API reference

useFilter

Matches items against a query using Intl.Collator for robust string matching. This hook is used when externally filtering items.

Input parameters

Accepts all Intl.CollatorOptions, plus the following option:

Return value

useFilteredItems

Returns the internally filtered items when called inside <Autocomplete.Root>.

Return value