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.6
usage	`import {useAutocomplete} from '@react-aria/autocomplete'`

View repository

GitHub

View package

NPM

Under construction

This hook is in beta. More documentation is coming soon!

API#

useAutocomplete<T>(
  (props: AriaAutocompleteOptions<T>,
  , state: AutocompleteState
)): AutocompleteAria<T>

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.

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
`inputProps`	`InputProps`	Props for the autocomplete input element. These should be passed to the input's aria hooks (e.g. useTextField/useSearchField/etc) 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, , node: Node<T> )) => 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.

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, node: Node<T> ) => 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. Note this is only applicable if virtual focus behavior is not turned off via `disableVirtualFocus`.
`disableVirtualFocus`	`boolean`	`false`	Whether the autocomplete should disable virtual focus, instead making the wrapped collection directly tabbable.
`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`

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`index`	`number`	The index of this node within its parent.
`aria-label`	`string`	An accessibility label for this node.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

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
`inputProps`	`InputProps`	Props for the autocomplete input element. These should be passed to the input's aria hooks (e.g. useTextField/useSearchField/etc) 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, , node: Node<T> )) => boolean`	A filter function that returns if the provided collection node should be filtered out of the collection.

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.
`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.
`value`	`T`	The current value (controlled).
`onChange`	`( (value: C )) => void`	Handler that is called when the value changes.
`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-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 MDN.
`autoComplete`	`string`	Describes the type of autocomplete functionality the input should provide if any. 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.

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.