Autocomplete

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

Commands

label

disableAutoFocusFirst

Example

Autocomplete.tsx

Autocomplete.css

import {Autocomplete} from './Autocomplete';
import {MenuItem} from './Menu';

<Autocomplete label="Commands">
  <MenuItem>Create new file...</MenuItem>
  <MenuItem>Create new folder...</MenuItem>
  <MenuItem>Assign to...</MenuItem>
  <MenuItem>Assign to me</MenuItem>
  <MenuItem>Change status...</MenuItem>
  <MenuItem>Change priority...</MenuItem>
  <MenuItem>Add label...</MenuItem>
  <MenuItem>Remove label...</MenuItem>
</Autocomplete>

Content

Autocomplete filters a Menu or ListBox using a TextField or SearchField. It can be used to build UI patterns such as command palettes, searchable menus, and filterable selects, and supports features such as static and dynamic collections, sections, disabled items, links, etc.

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.

Star Wars Character Search

import {Autocomplete} from './Autocomplete';
import {MenuItem} from './Menu';
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
      label="Star Wars Character Search"
      filter={null}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      items={list.items}
      renderEmptyState={() => 'No results found.'}>
      {(item) => (
        <MenuItem
          id={item.name}
          href={`https://www.starwars.com/databank/${
            item.name.toLowerCase().replace(/\s/g, '-')
          }`}
          target="_blank">
          {item.name}
        </MenuItem>
      )}
    </Autocomplete>
  );
}

API

<Autocomplete>
  <SearchField /> or <TextField />
  <Menu /> or <ListBox />
</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.