Component

Search

Search box

A search box with label and attached submit button. The component must be used within an HTML form. The search input has a name=”q” attribute and a customisable ID and NAME.

It can be used on white or on govuk-blue using the on_govuk_blue option.

Markup such as heading tags can be included in the label using the label_text option. Styling is not included in the component for heading tags in labels, however this is what the search results page does.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/search", {
} %>

Accessibility acceptance criteria

The search box should:

• be used inside a form with the role of ‘search’, to indicate it as a search landmark
• have a clear label to identify the search functionality, which is visible to all users

Other examples

Apply custom styling to the label and set search value (preview)

<%= render "govuk_publishing_components/components/search", {
  inline_label: false,
  label_text: sanitize("<h1>Search GOV.UK</h1>"),
  value: "driving licence"
} %>

Stop the label appearing inline (preview)

<%= render "govuk_publishing_components/components/search", {
  inline_label: false
} %>

No border (preview)

Sometimes we don’t need the grey border surrounding the input field, such as when the component is used on a black background

<%= render "govuk_publishing_components/components/search", {
  no_border: true
} %>

For use on govuk blue background (preview)

<%= render "govuk_publishing_components/components/search", {
  on_govuk_blue: true
} %>

Homepage (preview)

For use on the homepage.

<%= render "govuk_publishing_components/components/search", {
  label_text: "Search",
  inline_label: false,
  on_govuk_blue: true,
  label_size: "s",
  homepage: true,
  size: "large"
} %>

Change label text (preview)

<%= render "govuk_publishing_components/components/search", {
  label_text: "Search"
} %>

Set id for search input (preview)

<%= render "govuk_publishing_components/components/search", {
  id: "my_unique_id"
} %>

Large version (preview)

<%= render "govuk_publishing_components/components/search", {
  size: "large"
} %>

Large version on mobile only (preview)

<%= render "govuk_publishing_components/components/search", {
  size: "large-mobile"
} %>

Change field name (preview)

To be used if you need to change the default name ‘q’

<%= render "govuk_publishing_components/components/search", {
  name: "my_own_fieldname"
} %>

With aria controls attribute (preview)

The aria-controls attribute is a ‘relationship attribute’ which denotes which elements in a page an interactive element or set of elements has control over and affects.

For places like the finders where the page is updated dynamically after value changes to the input.

<%= render "govuk_publishing_components/components/search", {
  aria_controls: "wrapper"
} %>

With custom button text (preview)

The search box component may be used multiple times on a page – for example, on a guidance and regulation finder results page there is both the sitewide search in the header and also for the specific finder.

To avoid confusion, the text inside the button should be different for each form. This can be done by setting the button_text parameter.

This is visually hidden text – to check for changes use a screen reader or inspect the button element.

<%= render "govuk_publishing_components/components/search", {
  button_text: "Search absolutely everywhere"
} %>

With set label size (preview)

Allows the label text size to be set to xl, l, m, or s. If this is set, then inline_label is automatically set to false.

<%= render "govuk_publishing_components/components/search", {
  label_size: "xl"
} %>

Wrap label inside a heading (preview)

Puts the label inside a heading; heading level defaults to 2 if not set.

(The size of the label can still be set with label_size to appear more like a heading.)

<%= render "govuk_publishing_components/components/search", {
  wrap_label_in_a_heading: true,
  heading_level: 1
} %>

With margin bottom (preview)

Allows the spacing at the bottom of the component to be adjusted.

This accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. It defaults to having no margin bottom.

<%= render "govuk_publishing_components/components/search", {
  margin_bottom: 9
} %>

With margin bottom for the label (preview)

Allows the spacing between the label and the input be adjusted.

Requires inline_label to be false.

This accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. It defaults to having no margin bottom.

<%= render "govuk_publishing_components/components/search", {
  label_margin_bottom: 9,
  inline_label: false
} %>

With custom label class (preview)

Allows adding a custom class to the label of the component.

<%= render "govuk_publishing_components/components/search", {
  label_custom_class: "govuk-heading-xl"
} %>