Accessible autocomplete

The accessible autocomplete is a component that helps users choose answers from a list you provide. You can also use it to make the answers you get from users more consistent.

If you're asking users to provide their country or territory, the govuk-country-and-territory-autocomplete might be more appropriate.

accessible-autocomplete is a JavaScript autocomplete built from the ground up to be accessible. The design goals are:

• Accessibility: Following WAI-ARIA best practices and testing with assistive technologies.
• User experience: Supporting a wide variety of user needs.
• Compatibility: Working with recommended browsers and assistive technologies.

Try out the examples!

---

Support

The GOV.UK Design System team maintains the accessible autocomplete as a standalone component. However, we’re only able to put in minimal work to support it.

Read about our plans to maintain this component.

Read more about the types of support we can provide.

---

Installation / usage

Using npm and a module system

Install it by running:

npm install --save accessible-autocomplete

The accessibleAutocomplete function will render an autocomplete <input> and its accompanying suggestions and aria-live region. Your page should provide a <label> and a container element:

<label for="my-autocomplete">Select your country</label>
<div id="my-autocomplete-container"></div>

Then import it using a module system like Browserify / Webpack / Rollup, and call the accessibleAutocomplete function, providing an array of values:

import accessibleAutocomplete from 'accessible-autocomplete'

const countries = [
  'France',
  'Germany',
  'United Kingdom'
]

accessibleAutocomplete({
  element: document.querySelector('#my-autocomplete-container'),
  id: 'my-autocomplete', // To match it to the existing <label>.
  source: countries
})

If you want to use it as a replacement for a <select> element, read the Progressive enhancement section.

As a plain JavaScript module

You can copy the dist/accessible-autocomplete.min.js file to your JavaScript folder and import it into the browser:

<script type="text/javascript" src="assets/js/accessible-autocomplete.min.js"></script>

Styling the autocomplete

A stylesheet is included with the package at dist/accessible-autocomplete.min.css.

You can copy it to your stylesheets folder and import it into the browser:

<link rel="stylesheet" href="assets/css/accessible-autocomplete.min.css" />

You can also import it using Sass:

@import "accessible-autocomplete";

[!NOTE]

When styling the .autocomplete__input element, be aware that the autoselect option will render a second .autocomplete__hint input element for suggestion text. Both elements should be styled to ensure suggestions exactly align with the typed input text.

Using with Preact

If you already use Preact in your application, you can import a bundle that will use that:

import preact from 'preact'
import Autocomplete from 'accessible-autocomplete/preact'

preact.render(
  <Autocomplete id='autocomplete' source={suggest} />,
  document.querySelector('#container')
)

Try out the Preact example!

Preact versions

Preact v8.5.3 has been tested to work with the Accessible Autocomplete - although make sure to check out documented issues.

Preact 10.19.6 has been incompletely tested with the Accessible Autocomplete. No issues were found in Chrome and Firefox, but our automated tests for picking an option using the keyboard failed in Internet Explorer 11 (an issue we could not replicate when testing manually, though).

We recommend you carry out thorough testing if you wish to use this or later versions of Preact.

Using with React

If you already use React in your application, you can import a bundle that will use that:

import React from 'react'
import ReactDOM from 'react-dom'
import Autocomplete from 'accessible-autocomplete/react'

ReactDOM.render(
  <Autocomplete id='autocomplete' source={suggest} />,
  document.querySelector('#container')
)

Try out the React example!

React versions

React v15.5.4 has been tested to work with the Accessible Autocomplete - although make sure to check out documented issues.

React v15.6.2, v16.14.0, v17.0.2, and v18.2.0 have been incompletely tested with the Accessible Autocomplete. No undocumented issues were found (though be aware that React 18 dropped support for Internet Explorer)

We recommend you carry out thorough testing if you wish to use this or later versions of React.

API documentation

Required options

element

Type: HTMLElement

The container element in which the autocomplete will be rendered in.

id

Type: string

The id to assign to the autocomplete input field, to use with a <label for=id>. Not required if using enhanceSelectElement.

source

Type: Array | Function

An array of values to search when the user types in the input field, or a function to take what the user types and call a callback function with the results to be displayed.

An example of an array of values:

const countries = [
  'France',
  'Germany',
  'United Kingdom'
]

If source is a function, the arguments are: query: string, populateResults: Function

Similar to the source argument for typeahead.js, a backing data source for suggestions. query is what gets typed into the input field, which will callback to populateResults synchronously with the array of string results to display in the menu.

An example of a simple suggestion engine:

function suggest (query, populateResults) {
  const results = [
    'France',
    'Germany',
    'United Kingdom'
  ]
  const filteredResults = results.filter(result => result.indexOf(query) !== -1)
  populateResults(filteredResults)
}

Other options

inputClasses (default: null)

Type: string | null

Adds custom html classes to the generated input element.

If autoselect is set to true, the option hintClasses can be configured separately or it will default to the inputClasses value.

hintClasses (default: null)

Type: string | null

Adds custom html classes to the additional input element that appears when what the user typed matches the start of a suggestion.

If autoselect is set to true, the option inputClasses will be used as the default value unless hintClasses is set to an empty string ''.

menuAttributes (default: {})

Type: Object

Sets html attributes and their values on the generated ul menu element. Useful for adding aria-labelledby and setting to the value of the id attribute on your existing label, to provide context to an assistive technology user.

[!NOTE]

To maintain assistive technology support, menu attributes id, role and onMouseLeave cannot be overridden using menuAttributes. Setting className will append to the component default and menuClasses values.

menuClasses (default: null)

Type: string | null

Adds custom html classes to the generated ul menu element.

autoselect (default: false)

Type: Boolean

Set to true to highlight the first option when the user types in something and receives results. Pressing enter will select it.

confirmOnBlur (default: true)

Type: Boolean

The autocomplete will confirm the currently selected option when the user clicks outside of the component. Set to false to disable.

cssNamespace (default: 'autocomplete')

Type: string

Use this property to override the BEM block name that the JavaScript component will use. You will need to rewrite the CSS class names to use your specified block name.

defaultValue (default: '')

Type: string

Specify a string to prefill the autocomplete with.

displayMenu (default: 'inline')

Type: 'inline' | 'overlay'

You can set this property to specify the way the menu should appear, whether inline or as an overlay.

minLength (default: 0)

Type: number

The minimum number of characters that should be entered before the au