Skip to main content
Components

Search box

A search input with a label and an attached submit button, based on GOV.UK’s search component. Put it in your own form. Other props go on the input.

Import

import * as SearchBox from 'govuk-react/search-box';

Examples

Default

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

Large

Code
<SearchBox.Composite
  id="search"
  name="q"
  label="Search GOV.UK"
  labelSize="m"
  large
/>

Inverse

Code
<SearchBox.Composite
  id="search"
  name="q"
  label="Search"
  labelSize="s"
  large
  inverse
/>

Visually hidden label

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

With parts

Code
<SearchBox.Root>
  <SearchBox.Label htmlFor="search-parts">Search on GOV.UK</SearchBox.Label>
  <SearchBox.Wrapper>
    <SearchBox.Input id="search-parts" name="q" />
    <SearchBox.Button />
  </SearchBox.Wrapper>
</SearchBox.Root>

Autocomplete

Suggests searches once the user has typed 3 characters. Choosing one submits the form.

Code
<SearchBox.AutocompleteComposite {...args} />

Autocomplete open

Types a query on load, so the matching suggestions are open for visual regression.

Code
<SearchBox.Composite
  id="search-autocomplete-open"
  name="q"
  suggestions={suggestions}
/>

Autocomplete with parts

Suggestions from a server, with the query highlighted, using the parts.

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

API reference

SearchBox.Root

Wraps the search label, input and submit button.

PropType
inverse

For use on dark backgrounds, such as a GOV.UK blue homepage banner.

boolean
large

A larger input and button.

boolean

SearchBox.AssistiveHint

How to use the suggestions, for screen readers. Never shown.

PropType
asChild

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

boolean

SearchBox.Autocomplete

Suggests searches as the user types, around Wrapper, Listbox, Status and AssistiveHint. Without JavaScript the search box works as usual. Based on GOV.UK’s search with autocomplete, with behaviour from accessible-autocomplete.

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

SearchBox.AutocompleteComposite

A search box that suggests searches as the user types, based on GOV.UK’s search with autocomplete. Choosing a suggestion submits the form. Put it in your own form. Other props go on the input. Without JavaScript it’s Composite.

PropType
inverse

For use on dark backgrounds, such as a GOV.UK blue homepage banner.

boolean
large

A larger input and button.

boolean
idRequired

The input’s id, which the label points to.

string
label

The label text.

ReactNode
labelSize

The label size, from govuk-frontend’s label sizes.

"s" | "m" | "l" | "xl"
labelVisuallyHidden

Hide the label visually. It’s still read by screen readers.

boolean
buttonText

The submit button’s visually hidden text.

ReactNode
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
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
suggestions

The suggestions for the query, such as from onQueryChange. Only those containing the query show, unless filter is "none", such as for suggestions a server has already matched. Children are an alternative.

string[]

SearchBox.AutocompleteInput

Input, as the autocomplete’s combobox.

No props of its own. Other props are passed to the element it renders.

SearchBox.Button

The submit button, with a search icon. Children are its accessible name, “Search” by default.

No props of its own. Other props are passed to the element it renders.

SearchBox.Composite

A search input with a label and an attached submit button, based on GOV.UK’s search component. Put it in your own form. Other props go on the input.

PropType
inverse

For use on dark backgrounds, such as a GOV.UK blue homepage banner.

boolean
large

A larger input and button.

boolean
idRequired

The input’s id, which the label points to.

string
label

The label text.

ReactNode
labelSize

The label size, from govuk-frontend’s label sizes.

"s" | "m" | "l" | "xl"
labelVisuallyHidden

Hide the label visually. It’s still read by screen readers.

boolean
buttonText

The submit button’s visually hidden text.

ReactNode

SearchBox.Input

No props of its own. Other props are passed to the element it renders.

SearchBox.Label

PropType
size

The label size, from govuk-frontend’s label sizes.

"s" | "m" | "l" | "xl"
visuallyHidden

Hide the label visually. It’s still read by screen readers.

boolean

SearchBox.Listbox

The menu of suggestions, under the search box. Hidden until there are suggestions to show.

PropType
asChild

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

boolean

SearchBox.Match

The part of a suggestion that matches the query, in Option.

No props of its own. Other props are passed to the element it renders.

SearchBox.Option

A suggestion, in Listbox. Children are its text, which can hold Match.

PropType
asChild

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

boolean

SearchBox.Status

What screen readers hear about the suggestions. Visually hidden.

PropType
asChild

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

boolean

SearchBox.Wrapper

Lays out the input and submit button side by side.

No props of its own. Other props are passed to the element it renders.