Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Search Input

Use: Deployed USWDS v3
The Search input component lives in the global header of VA.gov and on search results pages, and can be paired with type-ahead functionality. Type-ahead displays up to five suggested search terms in a dropdown below the Search input field while the user is typing a query. The goal of type-ahead is to help Veterans navigate to relevant content more quickly by providing them with suggestions that match the characters they type.

Examples - v3

Default

View va-search-input Default in Storybook

With button text

View va-search-input with Button text in Storybook

Big

View va-search-input Big in Storybook

Small

View va-search-input small in Storybook

With Typeahead

View va-search-input with typeahead in Storybook

Examples - v1

Default

View va-search-input default and additional variations in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

Additional guidance for VA

When to use search input with type-ahead

  • The search input for site search should always be available as there will always be users who benefit from being able to search across VA.gov.
  • The search input for site search should always be used in concert with type-ahead functionality as type-ahead reduces cognitive load and can assist the user in building useful search queries quickly.
  • Type-ahead when used in a search input on a results page allows a user to filter a long list of search results.
  • Type-ahead should be used in mobile search where typing a query on a small, hand-held keyboard can be difficult.

When to consider something else

  • When free text input is allowed, do not use type-ahead in form fields where the user might assume they are limited to selecting a suggested term. Alternatively, provide a clear way for the user to add an entry if you do use type-ahead in a form field.

Placement

  • The search input component should only appear in the global header, on search results pages, and in search-related tools such as Resources and Support and Find a VA Form.
  • The search input component is revealed when a user interacts with the Search va-dropdown in the global header.
  • On search results pages, the search input appears below the header of the page and above the count of results in the main content well.
  • On search-related tools pages, the search input appears below the header of the page and above the linked resources or form links in the main content well.

How to use Search input with type-ahead

Type-ahead behavior

Up to five suggestions are presented to the user in a dropdown menu after they have typed three characters or more in the query input box. Selecting an item in the dropdown list will navigate the user to the search results page.

Suggestions are derived using two methods:

1. Search Algorithm that leverages the searches performed on VA.gov website.

  • A given term/phrase must be searched five times in a 24-hour period to appear as a suggestion.
  • If a suggestion does not meet those requirements, then it will be removed from circulation after a 30-day period.
  • Certain queries will not appear as suggestions for privacy and security purposes. (e.g., Names, SIN, etc.)
  • Terms related to geographical locations will not appear including cities and states.

2. A hardcoded list of specific terms curated to align with VA topics.

Terms that are added to this list include:

  • Hard to spell terms, particularly long ones (benefits, government)
  • Alphanumeric form titles (10-10ez)
  • Common veteran tasks
  • Top va.gov searches (benefits)
  • Best bets (e.g., Covid-19 vaccine)
  • Promoting va content to aid in wayfinding (e.g., Find a form or how do I?)

Ranking of suggestions

The five suggestions that are presented to users are selected from the suggestion database (combination of both the algorithm terms and the hardcoded terms).

The suggestions are ranked using the following rules:

  • Use query to find ALL possible matches
  • Sorted list by hardcoded/canned suggestion
  • Remove any hardcoded suggestions from the algorithm list
  • Then by algorithm / non-canned suggestion
  • Sort by best match (still preserving the above order)
  • Take the top five

Search.gov’s implementation of type-ahead does support fuzzy string matching to help with typos.

Code usage

Attributes and Properties

Property Attribute Type Default Description
big big boolean false If `true`, the component will use the big variant. Only available when `uswds` is `true`.
buttonText button-text string 'Search' Text displayed inside the search button
label label string 'Search' The aria-label for search input and button. Default is 'Search'.
small small boolean false If `true`, the component will use the small variant. Only available when `uswds` is `true`.
suggestions suggestions any An array of strings containing suggestions to be displayed in listbox. This component displays up to 5 suggestions.
uswds uswds boolean true Whether or not the component will use USWDS v3 styling.
value value string '' The value of the input field

Events

Name Description
component-library-analytics The event used to track usage of the component. This is emitted when the search button is clicked and when blur occurs on the input field.

API calls and dependent systems

Additional coding guidelines for type-ahead

The va-search component behaves as an input field with a submit button by default. In order to add type-ahead functionality, pass an array of suggestions that will be displayed below the input field. However, this component does not include logic to generate those suggestions.

Accessibility considerations

Refer to the U.S. Web Design System for accessibility guidance

Edit this page in GitHub (Permissions required)
Last updated: Mar 04, 2024