# 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 [Menu](Menu.html) or [ListBox](ListBox.html) using a [TextField](TextField.html) or [SearchField](SearchField.html). 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.

```tsx
import {Autocomplete} from 'vanilla-starter/Autocomplete';
import {MenuItem} from 'vanilla-starter/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"
      /*- begin highlight -*/
      filter={null}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      items={list.items}
      /*- end highlight -*/
      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

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