# Autocomplete

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

## Content

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

[Menu](Menu.html) and [ListBox](ListBox.html) 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.

### 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.

```tsx
import {Autocomplete} from 'react-aria-components';
import {SearchField} from 'vanilla-starter/SearchField';
import {ListBox, ListBoxItem} from 'vanilla-starter/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
      /*- begin highlight -*/
      filter={null}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}>
      {/*- end highlight -*/}
      <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>
  );
}
```

## Examples

<ExampleList
  tag="autocomplete"
  pages={props.pages}
/>

## API

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

### Autocomplete

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | — | The children wrapped by the autocomplete. Consists of at least an input element and a collection element to filter. |
| `defaultInputValue` | `string | undefined` | — | The default value of the autocomplete input (uncontrolled). |
| `disableAutoFocusFirst` | `boolean | undefined` | 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 | undefined` | false | Whether the autocomplete should disable virtual focus, instead making the wrapped collection directly tabbable. |
| `filter` | `((textValue: string, inputValue: string, node: Node<T>) => boolean) | undefined` | — | 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. |
| `inputValue` | `string | undefined` | — | The value of the autocomplete input (controlled). |
| `onInputChange` | `((value: string) => void) | undefined` | — | Handler that is called when the autocomplete input value changes. |
| `slot` | `string | null | undefined` | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |