Search InputUse: Deployed
With button text
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.
- 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
- When adding Search input with type-ahead to a search results page, match the global search results implementation on VA.gov.
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.
Attributes and Properties
||Text displayed inside the search button|
||The aria-label for search input and button. Default is 'Search'.|
||An array of strings containing suggestions to be displayed in listbox. This component displays up to 5 suggestions.|
||The value of 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.