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} />;API reference
Autocomplete.Root
| Prop | Type |
|---|---|
minLengthThe length the query needs before options show. 0 by default. | number |
filterWhich options match the query: "contains" (the default), "starts-with", or "none" for options that already match, such as results from a server. | Filter |
confirmOnBlurConfirm the highlighted option when focus leaves it. | boolean |
submitOnConfirmSubmit 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 |
onQueryChangeCalled 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 |
onConfirmCalled when the user confirms an option. Call | (value: string, event: CustomEvent<{ value: string; }>) => void |
queryTooShortAnnouncementHeard while the query is too short. | Translation |
noResultsAnnouncementHeard when no option matches. | Translation |
selectedOptionAnnouncementHeard after the results while an option is highlighted. | Translation |
resultsAnnouncementHeard when options match. | Translation |
Autocomplete.AssistiveHint
How to use the options, which describes the input while the query is empty. Never shown.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |