Autocomplete

An autocomplete combines a TextField or SearchField with a Menu or ListBox, allowing users to search or filter a list of suggestions.

Theme

disableAutoFocusFirst

import {CommandPalette} from './CommandPalette';
import {MenuItem} from './Menu';
import {Button} from './Button';
import {FilePlus2, FolderPlus, User, UserPen, CircleDotDashed, ChartPie, Tag} from 'lucide-react';
import {DialogTrigger, Text} from 'react-aria-components';
import {useState} from 'react';

function Example(props) {
  let [isOpen, setOpen] = useState(false);
  return (
    <DialogTrigger isOpen={isOpen} onOpenChange={setOpen}>
      <Button>Open Command Palette <kbd>⌘ J</kbd></Button>
      <CommandPalette
        {...props}
        isOpen={isOpen}
        onOpenChange={setOpen}>
        <MenuItem textValue="Create new file...">
          <FilePlus2 />
          <Text>Create new file...</Text>
        </MenuItem>
        <MenuItem textValue="Create new folder...">
          <FolderPlus />
          <Text>Create new folder...</Text>
        </MenuItem>
        <MenuItem textValue="Assign to...">
          <UserPen />
          <Text>Assign to...</Text>
        </MenuItem>
        <MenuItem textValue="Assign to me">
          <User />
          <Text>Assign to me</Text>
        </MenuItem>
        <MenuItem textValue="Change status...">
          <CircleDotDashed />
          <Text>Change status...</Text>
        </MenuItem>
        <MenuItem textValue="Change priority...">
          <ChartPie />
          <Text>Change priority...</Text>
        </MenuItem>
        <MenuItem textValue="Add label...">
          <Tag />
          <Text>Add label...</Text>
        </MenuItem>
        <MenuItem textValue="Remove label...">
          <Tag />
          <Text>Remove label...</Text>
        </MenuItem>
      </CommandPalette>
    </DialogTrigger>
  );
}

Content

Autocomplete filters a collection component using a TextField or SearchField. It can be used to build UI patterns such as command palettes, searchable menus, filterable selects, and more.

Menu and ListBox support virtual focus, which allows arrow key navigation within the list while the text input is focused. Use disableVirtualFocus to require the user to tab between the input and list.

disableVirtualFocus

disableAutoFocusFirst

import {Autocomplete, useFilter} from 'react-aria-components';
import {MenuTrigger, Menu, MenuItem} from './Menu';
import {Button} from './Button';
import {Popover} from './Popover';
import {SearchField} from './SearchField';

function Example(props) {
  let {contains} = useFilter({sensitivity: 'base'});

  return (
    <MenuTrigger>
      <Button>Add tag...</Button>
      <Popover style={{display: 'flex', flexDirection: 'column'}}>
        <Autocomplete {...props} filter={contains}>
          <SearchField
            autoFocus
            aria-label="Search tags"
            placeholder="Search tags"
            style={{margin: 4}} />
          <Menu style={{flex: 1}} renderEmptyState={() => 'No results.'}>
            <MenuItem>News</MenuItem>
            <MenuItem>Travel</MenuItem>
            <MenuItem>Shopping</MenuItem>
            <MenuItem>Business</MenuItem>
            <MenuItem>Entertainment</MenuItem>
            <MenuItem>Food</MenuItem>
            <MenuItem>Technology</MenuItem>
            <MenuItem>Health</MenuItem>
            <MenuItem>Science</MenuItem>
          </Menu>
        </Autocomplete>
      </Popover>
    </MenuTrigger>
  );
}

Asynchronous loading

When the filter prop is not set, the items are controlled. This example uses a backend API to perform searching instead of filtering a static list on the client.

Search Star Wars Characters

import {Autocomplete} from 'react-aria-components';
import {SearchField} from './SearchField';
import {ListBox, ListBoxItem} from './ListBox';
import {useAsyncList} from 'react-stately';

function AsyncLoadingExample() {
  let list = useAsyncList<{name: string}>({
    async load({signal, filterText}) {
      let res = await fetch(
        `https://swapi.py4e.com/api/people/?search=${filterText}`,
        {signal}
      );

      let json = await res.json();
      return {
        items: json.results
      };
    }
  });

  return (
    <Autocomplete
      filter={null}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}>
      <SearchField
        label="Search Star Wars Characters"
        placeholder="Search"
        style={{width: 250, margin: 8}} />
      <ListBox
        items={list.items}
        selectionMode="multiple"
        renderEmptyState={() => 'No results found.'}
        style={{height: 300}}>
        {(item) => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
      </ListBox>
    </Autocomplete>
  );
}

API

<Autocomplete>
  <SearchField /> or <TextField />
  <Menu />, <ListBox />, <TagGroup />, <GridList />, or <Table />
</Autocomplete>

Autocomplete

Name	Type	Default
`filter`	`( textValue: string, inputValue: string, node: Node<object> ) => boolean`	Default: —
An optional filter function used to determine if a option should be included in the autocomplete list. Include this if the items you are providing to your wrapped collection aren't filtered by default.
`disableAutoFocusFirst`	`boolean`	Default: `false`
Whether or not to focus the first item in the collection after a filter is performed. Note this is only applicable if virtual focus behavior is not turned off via `disableVirtualFocus`.
`disableVirtualFocus`	`boolean`	Default: `false`
Whether the autocomplete should disable virtual focus, instead making the wrapped collection directly tabbable.
`children`	`ReactNode`	Default: —
The children wrapped by the autocomplete. Consists of at least an input element and a collection element to filter.

`inputValue`	`string`	Default: —
The value of the autocomplete input (controlled).
`defaultInputValue`	`string`	Default: —
The default value of the autocomplete input (uncontrolled).
`onInputChange`	`(value: string) => void`	Default: —
Handler that is called when the autocomplete input value changes.