Components

Search

Search allows users to search for specific content if they know what search terms to use or can’t find desired content in the main navigation

Passed WCAG 2.1 AA

Default

Big variant

Small variant

Spanish default variant

Spanish big variant

Spanish small variant

<h3 class="site-preview-heading">Default</h3>
<section aria-label="Search component">
  <form class="usa-search" role="search">
    <label class="usa-sr-only" for="search-field">Search</label>
    <input class="usa-input" id="search-field" type="search" name="search" />
    <button class="usa-button" type="submit">
      <span class="usa-search__submit-text">Search </span
      ><img
        src="/preview/uswds/uswds-site/al-move-news/assets/img/usa-icons-bg/search--white.svg"
        class="usa-search__submit-icon"
        alt="Search"
      />
    </button>
  </form>
</section>

<h3 class="site-preview-heading">Big variant</h3>
<section aria-label="Big search component">
  <form class="usa-search usa-search--big" role="search">
    <label class="usa-sr-only" for="search-field-en-big">Search</label>
    <input
      class="usa-input"
      id="search-field-en-big"
      type="search"
      name="search"
    />
    <button class="usa-button" type="submit">
      <span class="usa-search__submit-text">Search </span
      ><img
        src="/preview/uswds/uswds-site/al-move-news/assets/img/usa-icons-bg/search--white.svg"
        class="usa-search__submit-icon"
        alt="Search"
      />
    </button>
  </form>
</section>

<h3 class="site-preview-heading">Small variant</h3>
<section aria-label="Small search component">
  <form class="usa-search usa-search--small" role="search">
    <label class="usa-sr-only" for="search-field-en-small">Search</label>
    <input
      class="usa-input"
      id="search-field-en-small"
      type="search"
      name="search"
    />
    <button class="usa-button" type="submit">
      <img
        src="/preview/uswds/uswds-site/al-move-news/assets/img/usa-icons-bg/search--white.svg"
        class="usa-search__submit-icon"
        alt="Search"
      />
    </button>
  </form>
</section>

<h3 class="site-preview-heading">Spanish default variant</h3>
<section aria-label="Default (Spanish) search component">
  <form class="usa-search" role="search">
    <label class="usa-sr-only" for="search-field-es">Buscar</label>
    <input class="usa-input" id="search-field-es" type="search" name="search" />
    <button class="usa-button" type="submit">
      <span class="usa-search__submit-text">Buscar </span
      ><img
        src="/preview/uswds/uswds-site/al-move-news/assets/img/usa-icons-bg/search--white.svg"
        class="usa-search__submit-icon"
        alt="Buscar"
      />
    </button>
  </form>
</section>

<h3 class="site-preview-heading">Spanish big variant</h3>
<section aria-label="Big (Spanish) search component">
  <form class="usa-search usa-search--big" role="search">
    <label class="usa-sr-only" for="search-field-es-big">Buscar</label>
    <input
      class="usa-input"
      id="search-field-es-big"
      type="search"
      name="search"
    />
    <button class="usa-button" type="submit">
      <span class="usa-search__submit-text">Buscar </span
      ><img
        src="/preview/uswds/uswds-site/al-move-news/assets/img/usa-icons-bg/search--white.svg"
        class="usa-search__submit-icon"
        alt="Buscar"
      />
    </button>
  </form>
</section>

<h3 class="site-preview-heading">Spanish small variant</h3>
<section aria-label="Small (Spanish) search component">
  <form class="usa-search usa-search--small" role="search">
    <label class="usa-sr-only" for="search-field-es-small">Buscar</label>
    <input
      class="usa-input"
      id="search-field-es-small"
      type="search"
      name="search"
    />
    <button class="usa-button" type="submit">
      <img
        src="/preview/uswds/uswds-site/al-move-news/assets/img/usa-icons-bg/search--white.svg"
        class="usa-search__submit-icon"
        alt="Buscar"
      />
    </button>
  </form>
</section>

Guidance

When to use the search component

  • Use site search. There will always be users who would benefit from being able to search your site.

When to consider something else

  • Very small sites. On single-page or very small sites, you may be able to get away without a search bar.

Usability guidance

  • Make the input at least 27 characters wide. Allow the search component to be as wide as possible, but a minimum of 27 characters wide. This allows users to enter multiple search terms and still be able to see all of them. The more users can see their search terms, the easier it is to review, verify, and submit their search query. Romance languages are about 20% longer than English, so account for text swell on multilingual websites.
  • The magnifying glass icon is effective. The magnifying glass has been shown to be almost universally recognized by users as an indicator of search, and doesn’t need to be visually paired with the word “Search” as long as it remains for screen readers.
  • Search terms should persist into search results. When displaying the search results, preload the search bar content with the original search terms.
  • Use a full search box on the home page. On a site’s home page the search function should appear as a search box instead of a link so users can locate it easily.
  • Don’t offer advanced search as the default. The majority of people will do a simple search with one or two search terms. If advanced search is offered, it increases the likelihood of mistakes.
  • Use a label even if it’s visually hidden. The form field should include a label for screen reader users.
  • The search button should be a submit button. This reduces the number of keystrokes required to use the form.

Accessibility guidance

Test the search component in your own project.

USWDS tested the search component for accessibility. You should test your implementation, too.

Use search accessibility tests
  • Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
  • Include the word “Search” in the button. Always include the word “search” inside the <button> element for screen readers. You can visually hide this text using the CSS class usa-sr-only or Sass mixin @include sr-only.

Using the search component

Search settings

Variable Description
$theme-search-font-family

Font family of the search.
$theme-search-min-width

Min-width of the search input.

Search variants

Variant Description

.usa-search--big

Search component with increased padding and font-size.

.usa-search--small

A compact variation of the search. Uses a magnifying glass icon for the submit button.

Accessibility test status

The USWDS team did 22 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
22 14 1 7 0

Overview of recent accessibility test results:

  • Passed: 14
  • Passed with exceptions: 1
  • Conditional: 7
  • Failed: 0

Learn more on the search accessibility tests page.

Package

  • Package usage: @forward "usa-search";
  • Dependencies: uswds-fonts, usa-button, usa-icon, usa-input, uswds-helpers

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-06-19 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2694

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved legibility in forced colors mode. Adds a consistent border in forced colors mode. More information: uswds#5147

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2021-12-14 2.13.0
  • Accessibility
  • Markup
  • Styles
 Breaking

Breaking Improved resilience of icon-only functionality. Updated to add a text equivalent if the image path is broken and does not load. More information: uswds#4274