Skip to main content
Primitives

Autocomplete

A port of GOV.UK's accessible-autocomplete that enhances your own input.

Used by govuk-react's search box.

Unstyled

The primitive on plain elements, with no GOV.UK markup or styles: what you start from in your own library.

Code
<>
  <label htmlFor="country">Country</label>
  <Autocomplete.Root>
    <Autocomplete.Input id="country" name="country" />
    <Autocomplete.Listbox>
      {countries.map((country) => (
        <Autocomplete.Option key={country} value={country}>
          {country}
        </Autocomplete.Option>
      ))}
      <Autocomplete.NoResults />
    </Autocomplete.Listbox>
    <Autocomplete.Status className="visually-hidden" />
    <Autocomplete.AssistiveHint />
  </Autocomplete.Root>
</>

In govuk-react

govuk-react's search box, built with this primitive.

Code
<SearchBox.Composite
  id="search"
  name="q"
/>

Usage

import * as Autocomplete from '@govuk-react/primitives/autocomplete';

<label htmlFor="country">Country</label>
<Autocomplete.Root onQueryChange={fetchCountries} onConfirm={setCountry}>
  <Autocomplete.Input id="country" name="country" />
  <Autocomplete.Listbox>
    {countries.map((country) => (
      <Autocomplete.Option key={country} value={country}>
        {country}
      </Autocomplete.Option>
    ))}
    <Autocomplete.NoResults />
  </Autocomplete.Listbox>
  <Autocomplete.Status className="visually-hidden" />
  <Autocomplete.AssistiveHint />
</Autocomplete.Root>;

A port of GOV.UK’s accessible-autocomplete that enhances your own input. Without JavaScript the input is a plain input. On upgrade it’s a combobox with accessible-autocomplete’s behaviour: options that match the query show in the Listbox, Up and Down move focus through them, Enter, Space or a click confirms one, and Escape closes the menu. Status tells screen readers how many options there are once the user pauses, so hide it visually with your own class, and AssistiveHint describes the input while the query is empty.

The input’s value is the query, and the options are whatever you render, so there is nothing else to control. onQueryChange is called when options are due, such as to fetch them, including for a query typed before hydration. filter sets which options match the query: “contains” (the default), “starts-with”, or “none” for options that already match, such as results from a server. Leave out NoResults to show nothing when no option matches.

minLength is the length the query needs before options show. onConfirm is called when the user confirms an option. With submitOnConfirm, confirming an option submits the form, and Enter submits it while no option is highlighted. As in accessible-autocomplete, focus leaving a highlighted option confirms it, unless confirmOnBlur is false. The status messages are English by default, and take a message for each plural form.

Not ported from accessible-autocomplete: showAllValues and its dropdown arrow, enhanceSelectElement, autoselect and its inline hint, displayMenu (style the Listbox instead) and the iOS position workaround.

accessible-autocomplete is Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT licence.

Inline script

To make the markup interactive before React hydrates, inline @govuk-react/primitives/inline/autocomplete-element.js, or render it from React on the server:

import { InlineScript, autocomplete } from '@govuk-react/primitives/inline-script';

<InlineScript script={autocomplete} nonce={nonce} />;

How inline scripts work

API reference

Autocomplete.Root

PropType
minLength

The length the query needs before options show. 0 by default.

number
filter

Which options match the query: "contains" (the default), "starts-with", or "none" for options that already match, such as results from a server.

Filter
confirmOnBlur

Confirm the highlighted option when focus leaves it. true by default.

boolean
submitOnConfirm

Submit the input's form when the user confirms an option, and let Enter submit it while the menu is open with no option highlighted.

boolean
onQueryChange

Called when the user changes the query and options are due, such as to fetch them. Also called once hydrated, with a query the user typed before hydration.

(query: string) => void
onConfirm

Called when the user confirms an option. Call preventDefault on the event to stop submitOnConfirm.

(value: string, event: CustomEvent<{ value: string; }>) => void
queryTooShortAnnouncement

Heard while the query is too short. %{count} is minLength.

Translation
noResultsAnnouncement

Heard when no option matches.

Translation
selectedOptionAnnouncement

Heard after the results while an option is highlighted. %{option}, %{position} and %{count}.

Translation
resultsAnnouncement

Heard when options match. %{count} is the number of options.

Translation

Autocomplete.AssistiveHint

How to use the options, which describes the input while the query is empty. Never shown.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Autocomplete.Input

The input, with an id and a label. A combobox once upgraded.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Autocomplete.Listbox

Holds the options. Hidden until there are options to show.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Autocomplete.NoResults

Shown in Listbox when no option matches the query. Leave it out to show nothing.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Autocomplete.Option

An option, in Listbox. Shown while it matches the query.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Autocomplete.Status

What screen readers hear about the options, once the user pauses. Hide it visually yourself.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean