Examples

The Autocomplete component is a parent component that adds autocomplete functionality to a TextField component.

Code

React

See Storybook for React guidance of this component.

Autocomplete items

An <Autocomplete> component accepts a list of items (JavaScript objects) that conform to the shape described by the table below.

Styles

The following CSS variables can be overridden to customize Autocomplete components:

Text Input Options

The <Autocomplete> component also makes use of a text field, which can be customized by the following variables:

Guidance

When to use

• If you are returning results from a known domain like a database of zip codes or a taxonomy of keywords
• If you have a list of options that would cause a dropdown to be unusually long

When to consider alternatives

• When users are choosing from a specific set of options. Consider checkboxes, radio buttons, or a dropdown in these cases.

Usage

• <Autocomplete> makes use of the <Downshift> component, maintained by Paypal: Downshift docs on Github. The above documented props are only those directly exposed by the <Autocomplete> component, but you can pass props specific to <Downshift> here as well, e.g. you can set the inputValue prop if you'd like to provide an initial value to the component or control the input more directly.
• We continue to use the ARIA 1.0 Combobox With List Autocomplete pattern. This decision was made ensures good compatibility with assistive devices (JAWS, NVDA, VoiceOver). This was done because the ARIA 1.1 markup pattern triggers a different behavior on containers with a role="combobox" attribute.
• Don't use placeholder text in autocomplete fields. Try to write a descriptive label that identifies what the user is searching for. People who have cognitive or visual disabilities have additional problems with placeholder text.
• The length of the text field provides a hint to users as to how much text to write. Do not ask users to write paragraphs of text in this component; use a textarea instead.

View the "Forms" guidelines for additional guidance and best practices.

Accessibility

• The <Autocomplete> component has taken special care to ensure accessibility for screenreader devices. It announces the number of results based on items matches with the inputValue string. The component also reads out the name of each list item when users arrow up or down.
• <Autocomplete> allows developers to add hint text in the <label> element. This hint <span> is added to the markup by passing a String into the hint prop.
• <Autocomplete> has a button (styled visually as a link) to clear the search, and refocus the <input> element. This resets the local state selectedItem to null, and will re-read the label and screenreader hint text.

Focus Management

• <Autocomplete> has a Boolean prop called focusTrigger. Adding this prop will set keyboard focus on the internal <Textfield>. Focus is set immediately when the componentDidMount() lifecycle method fires.
• In most cases, this isn't needed. It's useful when components are added dynamically, after the application has been rendered. All major screen readers (JAWS, NVDA, VoiceOver) have been tested with this feature, and announce the new input correctly.
• Instances that contain the focusTrigger prop may fire Downshift's onInputValueChange method, causing the inputValue to be set back to an empty string. In these cases, you may want to access Downshift's state reducer and manage your component's local state for blur and click events.

Component maturity