accessible-autocomplete: an autocomplete built around ARIA

A component whose first goal is assistive technology support

accessible-autocomplete helps users choose answers from a list you provide, and the README gives a second reason to use it: it also helps make the answers you get from users more consistent. The component is written in JavaScript and is published on npm as accessible-autocomplete.

What distinguishes it is the order of priorities. The README lists three design goals, and accessibility comes first: following WAI-ARIA best practices and testing with assistive technologies. User experience is second, supporting a wide variety of user needs. Compatibility is third, working with the recommended browsers and assistive technologies that the GOV.UK service manual publishes.

That ordering shows in the implementation. The component renders an input, a suggestions list and an aria-live region, and it expects your page to provide a label and a container element, so the accessible name comes from your own markup rather than from a generated attribute.

The audience is therefore not a designer picking a widget. It is a team with an accessibility requirement, usually in a public sector context, that needs a combobox they can defend in an audit. The example site linked from the README is the fastest way to judge the interaction, and the repository carries examples for a plain form, a form with a single input, an AJAX source, React and Preact.

The API is three options: element, id and source

The documented required options are short enough to hold in your head.

The element option takes an HTMLElement, the container the autocomplete is rendered into. The id option is a string assigned to the input field so it can be tied to a label for attribute, and it is not required when you use enhanceSelectElement. The source option is either an array of values to search as the user types, or a function that takes what the user typed and calls a callback with the results.

The array form is straightforward:

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

The function form is what you use for remote lookup. The README states that when source is a function, the arguments are query as a string and populateResults as a function, and the repository includes an example page driven by an AJAX source with its suggestions in a JSON file, which is the pattern to copy if your data is not static.

That choice between a static array and a callback is the main design decision you make as an integrator. A static array means the search runs in the browser against data you shipped, which is fast and needs no backend. A callback means every keystroke can trigger a request, which supports large or changing data sets and puts latency and error handling in your path.

The README notes that the source argument follows the same shape as the typeahead source argument, which is a useful hint if you are porting code from that library.

Three ways to install it, from npm to a copied file

The package is installed with npm:

npm install --save accessible-autocomplete

From there you provide the label and the container in your page:

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

and then import the component through a module system such as Browserify, Webpack or Rollup and call the accessibleAutocomplete function with your 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 would rather not add a build step, the package ships a prebuilt file you can copy into your JavaScript folder and load directly:

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

The stylesheet works the same way, with a link tag pointing at the copied minified CSS, or through Sass if you prefer to compile it yourself:

@import "accessible-autocomplete";

The plain script route is what makes the component usable in a static site without a JavaScript toolchain, which is a common situation for public sector content.

React and Preact bundles come with version caveats

The package exposes framework specific entry points, and the repository carries react.js and preact.js at the top level for them.

For React:

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')
)

For Preact:

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

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

The compatibility notes are the part to read carefully, because they are honest in a way that many component libraries are not. Preact v8.5.3 has been tested to work with the component. Preact 10.19.6 has been incompletely tested: no issues were found in Chrome and Firefox, but the automated tests for picking an option with the keyboard failed in Internet Explorer 11, a failure the team could not reproduce manually.

React is similar. React v15.5.4 has been tested to work. Versions v15.6.2, v16.14.0, v17.0.2 and v18.2.0 have been incompletely tested with no undocumented issues found, and the README reminds you that React 18 dropped Internet Explorer support. In both cases the recommendation is the same: carry out thorough testing if you use these versions or later ones.

That is a genuine caveat for an accessibility component, where keyboard behaviour is the whole point, and it is also a signal about how much the automated suite covers.

Progressive enhancement starts from an existing select

The README points to a Progressive enhancement section for the case where you want to use the component as a replacement for a select element, and the option name enhanceSelectElement appears in the API description as the case where the id option is not required.

That design is the reason this component is interesting for public sector forms. A form that asks for a country or a territory is usually shipped as a select, which works without JavaScript and which every assistive technology understands. Replacing it with a typeahead interface improves speed for long lists but risks losing the baseline behaviour, so the pattern is to enhance an existing select rather than to swap in a new widget from scratch.

The repository holds the pieces for that in the examples folder, where form.html and form-single.html sit alongside index.html and the AJAX source example.

The trade-off is styling. The README carries a note that when you style the .autocomplete__input element, the autoselect option renders a second .autocomplete__hint input element for the suggestion text, and that both elements should be styled so that the suggestions align exactly with the typed input text. That is a small detail with a visible consequence: if your design system does not style that second element, the suggestion text will not line up with what the user typed.

So the component gives you accessible behaviour and expects you to own the appearance.

Support is deliberately limited, and the README says so

The support section is the most important paragraph for an adopter. The GOV.UK Design System team maintains the accessible autocomplete as a standalone component, but states that they are only able to put in minimal work into support it. The project links to an issue describing the plans for maintaining the component and another explaining the types of support that can be provided.

That framing matters for anyone outside government. This is a component maintained by a team whose primary obligation is the GOV.UK Design System,. The stated intention is that it continues to be maintained, but the support commitment is explicitly thin, and the README does not promise response times or a fix cadence.

The licence is MIT, with the licence text in the repository as LICENSE.txt, and the package metadata records the MIT licence too. That is permissive enough for commercial reuse and for modification without any obligation beyond preserving the notice.

The release history is recent but uneven. Version 3.0.0 was published on 2024-04-19, v3.0.1 on 2024-09-12 and v3.0.2 on 2026-09-24, and the last push to main was on 2026-10-19. So the project is being worked on, with the most recent release landing less than a month before the last commit.

For the record, the repository also carries an accessibility-criteria.md file at the top level, which is a reasonable place to look for the standards the component is measured against, along with a CODEOWNERS file, a CHANGELOG.md and a CONTRIBUTING.md.

Where accessible-autocomplete is the wrong tool

The first case is the one the README names itself. If your field asks for a country or territory, the README suggests that the govuk-country-and-territory-autocomplete package might be more appropriate.

The second case is a long list of values that the user mostly knows already. A typeahead is a good fit when the user cannot recall the exact string, and a poor fit when they can, because typing to narrow a fifty item list of known values is slower than picking from a list. The component does not change that.

The third constraint is support. For a team that needs a component with an active issue backlog and a stated response commitment, minimal support is a real cost, and the README's own links on maintenance plans and support types are where you would go to judge it. The counterargument is that an accessibility component is expensive to rebuild, so a maintained-by-anyone component with a permissive licence can still be the cheapest option available.

The final limitation is the styling burden. The component hands you behaviour and ARIA semantics, and expects you to keep the input and the hint element aligned yourself. In a design system with its own tokens, that is work you would have had to do anyway.

Editorial conclusion

Adopt accessible-autocomplete when your form needs a typed suggestion list that must work with a screen reader and a keyboard, and you are willing to own the styling and the progressive enhancement path yourself. Skip it when your list is a short set of countries or territories, because the README points to a dedicated package for that case, or when you need a maintained, heavily supported component, since the maintaining team states it can only invest minimal effort in support. Verify three things first: that the option set you pass as source matches the list you expect users to see, that the autoselect option still aligns your styling, since it renders a second input for the suggestion text, and that the framework bundle you import matches your own React or Preact version, because the README documents only incompletely tested combinations for recent React releases. The last push to main was on 2026-10-19 and version 3.0.2 was published on 2026-09-24.

Frequently asked questions

Official sources

1. alphagov/accessible-autocomplete on GitHub
2. License: MIT
3. Project website
4. README
5. Releases