Search Input

USWDS v3

Examples

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 Type-ahead

View va-search-input with typeahead in Storybook

Usage

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.

Choosing the right component for the task

When deciding which component to use, consider the number of options available to the user. The total number of options will determine which component is right for the task:

• 2 - 5 options: Use Radio button when there are only a few options that can all be exposed at once.
• 6 - 15 options: Use Select for a limited number of options.
• 16 - 100 options: Use Combo box, which combines a select with typeahead functionality for easier selection.
• 101+ options: Use Search Input with typeahead to help users quickly find the right option from a large set.

Exceptions to consider when choosing a component

In some cases, there are common outliers and exceptions to account for:

• When the options are known and memorable. Options like months, days, states, countries, and other familiar data groupings can be considered exceptions to choosing the right component. For example, the Combo box works well for Countries or States that benefit from both scrolling or typing to find the selection. Consider your user and evaluate if typing or comparing options would be a better user experience when finalizing the component choice.
• When the radio button labels are long or radio tiles contain descriptive text. Long labels within a dropdown might make it difficult to read and select an option. Radio tiles often include descriptive text that cannot be used in a dropdown. In these cases, Radio button may be the better choice.
• When the task is to sort a set of results. Use the dedicated Sort component, which utilizes a Select component as its foundation.

Contact the Design System team via #platform-design-system for help if you have other use cases that may be considered exceptions.

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

Web

API calls and dependent systems

• Search.gov type-ahead suggestions API

Additional coding guidelines for type-ahead

• When adding Search Input with type-ahead to a search results page, match the global search results implementation on VA.gov.
• The Search Input 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.

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 via the 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.

Choosing between web variations

There are 3 size variations of the Search Input component.

• Use the default variation for standard search patterns. Use the default size when the search input is embedded in a content area alongside other page elements, such as on search results pages, tool-specific pages (Resources and Support, Find a Form), and the homepage search. This is the most common variation.
• Use the big variation when search is the primary action on the page. Use the big size when the search input serves as a prominent, standalone call to action and is not paired with a results list on the same page. For example, a reference number lookup that navigates the user to a new view or displays an inline status.
• Use the small variation when space or visual hierarchy is a constraint. The small size can be appropriate in compact interfaces where a full-sized search input would dominate the layout, such as in toolbars or panels. This variation has no defined production usage pattern at this time. Consult the Design System team if you are considering this variation.

Accessibility considerations

Privacy guidance

An open text field that allows users to enter a search query has a high risk for users to enter Personally Identifiable Information (PII) or Protected Health Information (PHI).

If search entries are tracked, proper procedures must be in place for stripping/redacting PII/PHI from logs.

If the user’s entered query is passed in a URL parameter, that parameter value should be stripped from any logs.

Learn more about PII/PHI on the VA Platform website

Provide feedback

Share your feedback, report issues, or suggest improvements for the Search Input component. Your input helps us make the design system better for everyone.

• Get immediate support in #platform-design-system for technical or urgent issues.
• Explore all feedback channels for additional ways to share your input.