beta

useAutocomplete

Provides the behavior and accessibility implementation for an autocomplete component. An autocomplete combines a text input with a collection, allowing users to filter the collection's contents match a query.

install	`yarn add @react-aria/autocomplete`
version	3.0.0-beta.1
usage	`import {useAutocomplete} from '@react-aria/autocomplete'`

View repository

GitHub

View package

NPM

API#

useAutocomplete(
  (props: AriaAutocompleteOptions,
  , state: AutocompleteState
)): AutocompleteAria

Features#

Autocomplete can be implemented using the <datalist> HTML element, but this has limited functionality and behaves differently across browsers. useAutocomplete helps achieve accessible text input and collection that can be styled as needed.

useAutocomplete can be used to build UI patterns such as command palettes, searchable menus, and filterable selects.

Flexible – Support for multiple input types and collection types, controlled and uncontrolled state, and custom filter functions.
Keyboard navigation – an Autocomplete can be navigated using the arrow keys, along with page up/down, home/end, etc. The list of options is filtered while typing into the input, and items can be selected with the enter key.
Accessible – Follows the ARIA autocomplete pattern, with support for any collections.

Anatomy#

An autocomplete consists of a text input that displays the current value and a collection of items. Users can type within the input to filter the collection. useAutocomplete handles exposing the correct ARIA attributes for accessibility for each of the elements comprising the autocomplete.

useAutocomplete returns props that you should spread onto the appropriate elements:

Name	Type	Description
`textFieldProps`	`AriaTextFieldProps`	Props for the autocomplete textfield/searchfield element. These should be passed to the textfield/searchfield aria hooks respectively.
`collectionProps`	`CollectionOptions`	Props for the collection, to be passed to collection's respective aria hook (e.g. useMenu).
`collectionRef`	`RefObject<HTMLElement \| null>`	Ref to attach to the wrapped collection.
`filter`	`( (nodeTextValue: string )) => boolean`	A filter function that returns if the provided collection node should be filtered out of the collection.

State is managed by the useAutocompleteState hook from @react-stately/autocomplete. The state object should be passed as an option to useAutocomplete.

Example#

This example uses React Aria Components and shows how, if you need to build your own Autocomplete component, you can integrate it with existing React Aria Components. This Autocomplete uses a SearchField as the input and controls a ListBox. See those docs for examples of what they can do or how to customize them. This Autocomplete renders no dom, so see those components for styling as well.

import {AriaAutocompleteProps, useAutocomplete} from '@react-aria/autocomplete';
import {useAutocompleteState} from '@react-stately/autocomplete';
import {useRef} from 'react';
import {
  Label,
  Text,
  InputContext,
  Input,
  Provider,
  SearchFieldContext,
  SearchField,
  ListBox,
  ListBoxItem,
  useFilter,
  UNSTABLE_InternalAutocompleteContext
} from 'react-aria-components'

interface AutocompleteProps extends AriaAutocompleteProps {}

function Autocomplete(props: AutocompleteProps) {
  let {contains} = useFilter({ sensitivity: 'base' });
  let filter = (textValue, inputValue) => contains(textValue, inputValue);
  let {disableAutoFocusFirst} = props;
  let state = useAutocompleteState(props);
  let inputRef = useRef<HTMLInputElement | null>(null);
  let collectionRef = useRef<HTMLElement>(null);
  let {
    textFieldProps,
    collectionProps,
    collectionRef: mergedCollectionRef,
    filter: filterFn
  } = useAutocomplete({
    ...props,
    filter,
    disableAutoFocusFirst,
    inputRef,
    collectionRef
  }, state);

  return (
    <Provider
      values={[
        [SearchFieldContext, textFieldProps],
        [InputContext, {ref: inputRef}],
        [UNSTABLE_InternalAutocompleteContext, {
          filter: filterFn,
          collectionProps,
          collectionRef: mergedCollectionRef
        }]
      ]}>
      {props.children}
    </Provider>
  );
};

<div className="autocomplete">
  <Autocomplete>
    <SearchField>
      <Label>Favorite animal</Label>
      <Input />
      <Text slot="description">Please select a pet below.</Text>
    </SearchField>
    <ListBox selectionMode="single" aria-label="Possible pets">
      <ListBoxItem id="red panda">Red Panda</ListBoxItem>
      <ListBoxItem id="cat">Cat</ListBoxItem>
      <ListBoxItem id="dog">Dog</ListBoxItem>
      <ListBoxItem id="aardvark">Aardvark</ListBoxItem>
      <ListBoxItem id="kangaroo">Kangaroo</ListBoxItem>
      <ListBoxItem id="snake">Snake</ListBoxItem>
    </ListBox>
  </Autocomplete>
</div>

import {
  AriaAutocompleteProps,
  useAutocomplete
} from '@react-aria/autocomplete';
import {useAutocompleteState} from '@react-stately/autocomplete';
import {useRef} from 'react';
import {
  Input,
  InputContext,
  Label,
  ListBox,
  ListBoxItem,
  Provider,
  SearchField,
  SearchFieldContext,
  Text,
  UNSTABLE_InternalAutocompleteContext,
  useFilter
} from 'react-aria-components';

interface AutocompleteProps extends AriaAutocompleteProps {}

function Autocomplete(props: AutocompleteProps) {
  let { contains } = useFilter({ sensitivity: 'base' });
  let filter = (textValue, inputValue) =>
    contains(textValue, inputValue);
  let { disableAutoFocusFirst } = props;
  let state = useAutocompleteState(props);
  let inputRef = useRef<HTMLInputElement | null>(null);
  let collectionRef = useRef<HTMLElement>(null);
  let {
    textFieldProps,
    collectionProps,
    collectionRef: mergedCollectionRef,
    filter: filterFn
  } = useAutocomplete({
    ...props,
    filter,
    disableAutoFocusFirst,
    inputRef,
    collectionRef
  }, state);

  return (
    <Provider
      values={[
        [SearchFieldContext, textFieldProps],
        [InputContext, { ref: inputRef }],
        [UNSTABLE_InternalAutocompleteContext, {
          filter: filterFn,
          collectionProps,
          collectionRef: mergedCollectionRef
        }]
      ]}
    >
      {props.children}
    </Provider>
  );
}

<div className="autocomplete">
  <Autocomplete>
    <SearchField>
      <Label>Favorite animal</Label>
      <Input />
      <Text slot="description">
        Please select a pet below.
      </Text>
    </SearchField>
    <ListBox
      selectionMode="single"
      aria-label="Possible pets"
    >
      <ListBoxItem id="red panda">Red Panda</ListBoxItem>
      <ListBoxItem id="cat">Cat</ListBoxItem>
      <ListBoxItem id="dog">Dog</ListBoxItem>
      <ListBoxItem id="aardvark">Aardvark</ListBoxItem>
      <ListBoxItem id="kangaroo">Kangaroo</ListBoxItem>
      <ListBoxItem id="snake">Snake</ListBoxItem>
    </ListBox>
  </Autocomplete>
</div>

import {
  AriaAutocompleteProps,
  useAutocomplete
} from '@react-aria/autocomplete';
import {useAutocompleteState} from '@react-stately/autocomplete';
import {useRef} from 'react';
import {
  Input,
  InputContext,
  Label,
  ListBox,
  ListBoxItem,
  Provider,
  SearchField,
  SearchFieldContext,
  Text,
  UNSTABLE_InternalAutocompleteContext,
  useFilter
} from 'react-aria-components';

interface AutocompleteProps
  extends
    AriaAutocompleteProps {}

function Autocomplete(
  props:
    AutocompleteProps
) {
  let { contains } =
    useFilter({
      sensitivity: 'base'
    });
  let filter = (
    textValue,
    inputValue
  ) =>
    contains(
      textValue,
      inputValue
    );
  let {
    disableAutoFocusFirst
  } = props;
  let state =
    useAutocompleteState(
      props
    );
  let inputRef = useRef<
    | HTMLInputElement
    | null
  >(null);
  let collectionRef =
    useRef<HTMLElement>(
      null
    );
  let {
    textFieldProps,
    collectionProps,
    collectionRef:
      mergedCollectionRef,
    filter: filterFn
  } = useAutocomplete({
    ...props,
    filter,
    disableAutoFocusFirst,
    inputRef,
    collectionRef
  }, state);

  return (
    <Provider
      values={[
        [
          SearchFieldContext,
          textFieldProps
        ],
        [InputContext, {
          ref: inputRef
        }],
        [
          UNSTABLE_InternalAutocompleteContext,
          {
            filter:
              filterFn,
            collectionProps,
            collectionRef:
              mergedCollectionRef
          }
        ]
      ]}
    >
      {props.children}
    </Provider>
  );
}

<div className="autocomplete">
  <Autocomplete>
    <SearchField>
      <Label>
        Favorite animal
      </Label>
      <Input />
      <Text slot="description">
        Please select a
        pet below.
      </Text>
    </SearchField>
    <ListBox
      selectionMode="single"
      aria-label="Possible pets"
    >
      <ListBoxItem id="red panda">
        Red Panda
      </ListBoxItem>
      <ListBoxItem id="cat">
        Cat
      </ListBoxItem>
      <ListBoxItem id="dog">
        Dog
      </ListBoxItem>
      <ListBoxItem id="aardvark">
        Aardvark
      </ListBoxItem>
      <ListBoxItem id="kangaroo">
        Kangaroo
      </ListBoxItem>
      <ListBoxItem id="snake">
        Snake
      </ListBoxItem>
    </ListBox>
  </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-ListBox {
    flex: 1;
    overflow: auto;
  }

  .react-aria-Label {
    margin-bottom: .5em;
  }
}

@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-ListBox {
    flex: 1;
    overflow: auto;
  }

  .react-aria-Label {
    margin-bottom: .5em;
  }
}

@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-ListBox {
    flex: 1;
    overflow: auto;
  }

  .react-aria-Label {
    margin-bottom: .5em;
  }
}

Styled examples#

See Autocomplete examples for a sense of the things that you can build with the useAutocomplete hook.

Internationalization#

useAutocomplete handles some aspects of internationalization automatically. For example, VoiceOver announcements about the item focus, count, and selection are localized. You are responsible for localizing all labels and option content that is passed into the autocomplete.

Name	Type	Default	Description
`inputRef`	`RefObject<HTMLInputElement \| null>`	—	The ref for the wrapped collection element.
`collectionRef`	`RefObject<HTMLElement \| null>`	—	The ref for the wrapped collection element.
`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.
`disableAutoFocusFirst`	`boolean`	`false`	Whether or not to focus the first item in the collection after a filter is performed.
`inputValue`	`string`	—	The value of the autocomplete input (controlled).
`defaultInputValue`	`string`	—	The default value of the autocomplete input (uncontrolled).
`onInputChange`	`( (value: string )) => void`	—	Handler that is called when the autocomplete input value changes.

Name	Type	Description
`current`	`T`

Properties

Name	Type	Description
`inputValue`	`string`	The current value of the autocomplete input.
`focusedNodeId`	`string \| null`	The id of the current aria-activedescendant of the autocomplete input.

Methods

Method	Description
`setInputValue( (value: string )): void`	Sets the value of the autocomplete input.
`setFocusedNodeId( (value: string \| \| null )): void`	Sets the id of the current aria-activedescendant of the autocomplete input.

Name	Type	Description
`textFieldProps`	`AriaTextFieldProps`	Props for the autocomplete textfield/searchfield element. These should be passed to the textfield/searchfield aria hooks respectively.
`collectionProps`	`CollectionOptions`	Props for the collection, to be passed to collection's respective aria hook (e.g. useMenu).
`collectionRef`	`RefObject<HTMLElement \| null>`	Ref to attach to the wrapped collection.
`filter`	`( (nodeTextValue: string )) => boolean`	A filter function that returns if the provided collection node should be filtered out of the collection.

Name	Type	Default	Description
`aria-activedescendant`	`string`	—	Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
`aria-autocomplete`	`'none' \| 'inline' \| 'list' \| 'both'`	—	Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made.
`aria-haspopup`	`boolean \| 'false' \| 'true' \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`enterKeyHint`	`'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'`	—	An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint].
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`validate`	`( (value: string )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<T> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<T> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`value`	`string`	—	The current value (controlled).
`defaultValue`	`string`	—	The default value (uncontrolled).
`onChange`	`( (value: T )) => void`	—	Handler that is called when the value changes.
`label`	`ReactNode`	—	The content to display as the label.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`autoComplete`	`string`	—	Describes the type of autocomplete functionality the input should provide if any. See MDN.
`maxLength`	`number`	—	The maximum number of characters supported by the input. See MDN.
`minLength`	`number`	—	The minimum number of characters required by the input. See MDN.
`pattern`	`string`	—	Regex pattern that the value of the input must match to be valid. See MDN.
`type`	`'text' \| 'search' \| 'url' \| 'tel' \| 'email' \| 'password' \| string & & {}`	—	The type of input to render. See MDN.
`inputMode`	`'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'`	—	Hints at the type of data that might be entered by the user while editing the element or its contents. See MDN.
`autoCorrect`	`string`	—	An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See MDN.
`spellCheck`	`string`	—	An enumerated attribute that defines whether the element may be checked for spelling errors. See MDN.
`name`	`string`	—	The name of the input element, used when submitting an HTML form. See MDN.
`onCopy`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user copies text. See MDN.
`onCut`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user cuts text. See MDN.
`onPaste`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user pastes text. See MDN.
`onCompositionStart`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a text composition system starts a new text composition session. See MDN.
`onCompositionEnd`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a text composition system completes or cancels the current text composition session. See MDN.
`onCompositionUpdate`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a new character is received in the current text composition session. See MDN.
`onSelect`	`ReactEventHandler<HTMLInputElement>`	—	Handler that is called when text in the input is selected. See MDN.
`onBeforeInput`	`FormEventHandler<HTMLInputElement>`	—	Handler that is called when the input value is about to be modified. See MDN.
`onInput`	`FormEventHandler<HTMLInputElement>`	—	Handler that is called when the input value is modified. See MDN.
`aria-errormessage`	`string`	—	Identifies the element that provides an error message for the object.

'valid' | 'invalid'

string | string[]

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Name	Type	Description
`shouldUseVirtualFocus`	`boolean`	Whether the collection items should use virtual focus instead of being focused directly.
`disallowTypeAhead`	`boolean`	Whether typeahead is disabled.
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

Provides state management for an autocomplete component.

useAutocompleteState(
  (props: AutocompleteStateOptions
)): AutocompleteState

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