AutocompleteStatusdevelopment

Help users choose one or more options from a long list by typing to filter the list as they go.

Guidance

An autocomplete is suitable when users need to choose from a list that is too long to scan comfortably, for example more than around 15 options, and they are likely to know the name of what they are looking for, such as a country or an organisation.

For a short list, use radio buttons or checkboxes so that every option is visible at once. Do not use an autocomplete where users need to compare or browse the options.

Use the single selection variant when only one answer is allowed. Use the multiple selection variant when users need to choose several options from a long list. Each choice is shown as a removable item and is announced to screen reader users as it is added or removed.

This pattern progressively enhances a native <select>, or <select multiple> for multiple selection, so the field still works without JavaScript. The options, field name, any pre-selected options and the label association are taken from the <select>. The option text is shown and searched, and the option value is submitted with the form.

Single selection example

Open in a new tab

Code

<form class="form" action="#" novalidate>
    <h1 class="visuallyhidden">Autocomplete</h1>
    <label class="label" for="country">
        Country of residence
        <span class="label__hint">
            Start typing, then choose a country from the list
        </span>
    </label>
    <div class="autocomplete js-autocomplete">
        <select class="select" id="country" name="country">
            <option value>Choose a country</option>
            <option value="AU">Australia</option>
            <option value="AT">Austria</option>
            <option value="BE">Belgium</option>
            <option value="CA">Canada</option>
            <option value="DK">Denmark</option>
            <option value="FI">Finland</option>
            <option value="FR">France</option>
            <option value="DE">Germany</option>
            <option value="IS">Iceland</option>
            <option value="IE">Ireland</option>
            <option value="IT">Italy</option>
            <option value="NL">Netherlands</option>
            <option value="NZ">New Zealand</option>
            <option value="NO">Norway</option>
            <option value="PT">Portugal</option>
            <option value="ES">Spain</option>
            <option value="SE">Sweden</option>
            <option value="CH">Switzerland</option>
            <option value="GB">United Kingdom</option>
            <option value="US">United States</option>
        </select>
    </div>
</form>

import autocomplete from '@stormid/autocomplete';

autocomplete('.js-autocomplete', { displayTemplate: option => option.label });

Multiple selection example

Open in a new tab

Code

<form class="form" action="#" novalidate>
    <h1 class="visuallyhidden">Multiple selection autocomplete</h1>
    <label class="label" for="countries">
        Countries you have visited
        <span class="label__hint">
            Start typing, then choose as many countries as you need
        </span>
    </label>
    <div class="autocomplete autocomplete--multiple js-autocomplete">
        <select class="select" id="countries" name="countries" multiple>
            <option value="AU">Australia</option>
            <option value="AT">Austria</option>
            <option value="BE">Belgium</option>
            <option value="CA">Canada</option>
            <option value="DK">Denmark</option>
            <option value="FI">Finland</option>
            <option value="FR">France</option>
            <option value="DE">Germany</option>
            <option value="IS">Iceland</option>
            <option value="IE">Ireland</option>
            <option value="IT">Italy</option>
            <option value="NL">Netherlands</option>
            <option value="NZ">New Zealand</option>
            <option value="NO">Norway</option>
            <option value="PT">Portugal</option>
            <option value="ES">Spain</option>
            <option value="SE">Sweden</option>
            <option value="CH">Switzerland</option>
            <option value="GB">United Kingdom</option>
            <option value="US">United States</option>
        </select>
    </div>
</form>

import autocomplete from '@stormid/autocomplete';

autocomplete('.js-autocomplete', { displayTemplate: option => option.label });

Multiple selection is set by the multiple attribute on the <select>. Each selected value is submitted under the same field name.

Dependencies and installation

Package	Installation
@stormid/autocomplete	`npm i -S @stormid/autocomplete`

Acceptance criteria

The following is a list of example acceptance criteria to test against when using this pattern. These criteria should test that the specific markup requirements are met, and that the autocomplete behaves visually and functionally as expected.

For validation in developer tools / web inspector

The text
```
<input>
```
element should have an attribute of
```
role="combobox"
```
and a matching
```
<label>
```
element
The combobox should have an
```
aria-controls
```
attribute that matches the ID of the list of options, and an
```
aria-expanded
```
attribute that describes whether the list is shown
The list of options should have an attribute of
```
role="listbox"
```
, and each option should have an attribute of
```
role="option"
```
The highlighted option should be referenced by the
```
aria-activedescendant
```
attribute of the combobox
The selected value should be submitted with the form, using the name of the original
```
<select>
```
In the multiple selection variant, the button to remove each selected option should be an HTML
```
<button>
```
with an accessible name that includes the option, for example 'Remove France'

For visual validation

The text input should have a clearly visible focus style which meets accessibility contrast requirements
The highlighted option should be clearly visually distinguishable from the other options
The list of options should be hidden until the user types into the input
In the multiple selection variant, each selected option should be visible, and its remove button should be at least 24 by 24 pixels with a clearly visible focus style

For functional validation

Without JavaScript, the native
```
<select>
```
should be shown and submit the chosen value(s)
The list of options should be filtered to those that contain the text typed into the input, once at least two characters have been typed
The number of available results should be announced to screen readers, and a message should be shown and announced when there are no results
The 'down arrow' and 'up arrow' keys should move the highlight through the options, while keyboard focus stays in the input
The 'Enter' key, or a click, should choose the highlighted option and close the list
The 'Escape' key should close the list without choosing an option
In the single selection variant, the chosen option should be shown in the input
In the multiple selection variant, a chosen option should be removed from the list of options, so it can't be chosen twice
In the multiple selection variant, adding or removing an option should be announced to screen readers
In the multiple selection variant, pressing 'Backspace' in an empty input should remove the last selected option

UI Patterns

AutocompleteStatusdevelopment

Guidance

Single selection example

Code

Multiple selection example

Code

Dependencies and installation

Acceptance criteria

For validation in developer tools / web inspector

For visual validation

For functional validation

References