alpha

Autocomplete

A autocomplete combines a text input with a menu, allowing users to filter a list of options to items matching a query.

install	`yarn add react-aria-components`
version	1.6.0
usage	`import {UNSTABLE_Autocomplete} from 'react-aria-components'`

View ARIA pattern

Under construction

This component is in alpha. More documentation is coming soon!

Example#

import {Menu, MenuItem, UNSTABLE_Autocomplete as Autocomplete, useFilter} from 'react-aria-components';
import {MySearchField} from './SearchField';

function Example() {
  let { contains } = useFilter({ sensitivity: 'base' });
  return (
    <div className="autocomplete">
      <Autocomplete filter={contains}>
        <MySearchField placeholder="Search commands..." />
        <Menu>
          <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>
        </Menu>
      </Autocomplete>
    </div>
  );
}

import {
  Menu,
  MenuItem,
  UNSTABLE_Autocomplete as Autocomplete,
  useFilter
} from 'react-aria-components';
import {MySearchField} from './SearchField';

function Example() {
  let { contains } = useFilter({ sensitivity: 'base' });
  return (
    <div className="autocomplete">
      <Autocomplete filter={contains}>
        <MySearchField placeholder="Search commands..." />
        <Menu>
          <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>
        </Menu>
      </Autocomplete>
    </div>
  );
}

import {
  Menu,
  MenuItem,
  UNSTABLE_Autocomplete
    as Autocomplete,
  useFilter
} from 'react-aria-components';
import {MySearchField} from './SearchField';

function Example() {
  let { contains } =
    useFilter({
      sensitivity: 'base'
    });
  return (
    <div className="autocomplete">
      <Autocomplete
        filter={contains}
      >
        <MySearchField placeholder="Search commands..." />
        <Menu>
          <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>
        </Menu>
      </Autocomplete>
    </div>
  );
}

Show CSS

@import "@react-aria/example-theme";

.autocomplete {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 300px;
  height: 180px;
  border: 1px solid var(--border-color);
  padding: 16px;
  border-radius: 10px;
  background: var(--overlay-background);

  .react-aria-SearchField {
    width: 100%;
  }

  .react-aria-Menu {
    flex: 1;
    overflow: auto;
  }
}

@import "@react-aria/example-theme";

.autocomplete {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 300px;
  height: 180px;
  border: 1px solid var(--border-color);
  padding: 16px;
  border-radius: 10px;
  background: var(--overlay-background);

  .react-aria-SearchField {
    width: 100%;
  }

  .react-aria-Menu {
    flex: 1;
    overflow: auto;
  }
}

@import "@react-aria/example-theme";

.autocomplete {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 300px;
  height: 180px;
  border: 1px solid var(--border-color);
  padding: 16px;
  border-radius: 10px;
  background: var(--overlay-background);

  .react-aria-SearchField {
    width: 100%;
  }

  .react-aria-Menu {
    flex: 1;
    overflow: auto;
  }
}

Anatomy#

Autocomplete is a controller for a child text input, such as a TextField or SearchField, and a collection component such as a Menu or ListBox. It enables the user to filter a list of items, and navigate via the arrow keys while keeping focus on the input.

import {Menu, SearchField, UNSTABLE_Autocomplete as Autocomplete} from 'react-aria-components';

<Autocomplete>
  <SearchField />
  <Menu />
</Autocomplete>

import {
  Menu,
  SearchField,
  UNSTABLE_Autocomplete as Autocomplete
} from 'react-aria-components';

<Autocomplete>
  <SearchField />
  <Menu />
</Autocomplete>

import {
  Menu,
  SearchField,
  UNSTABLE_Autocomplete
    as Autocomplete
} from 'react-aria-components';

<Autocomplete>
  <SearchField />
  <Menu />
</Autocomplete>

Props#

Name	Type	Description
`children`	`ReactNode`	The children wrapped by the autocomplete. Consists of at least an input element and a collection element to filter.
`filter`	`( (textValue: string, , inputValue: string )) => boolean`	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`	The value of the autocomplete input (controlled).
`defaultInputValue`	`string`	The default value of the autocomplete input (uncontrolled).

Events

Name	Type	Description
`onInputChange`	`( (value: string )) => void`	Handler that is called when the autocomplete input value changes.

Layout

Name	Type	Description
`slot`	`string \| null`	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.