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

Select

Use: Deployed English, Spanish
A select box allows users to select one option from a list.

View va-select in Storybook

Usage

When to use select

  • Use sparingly — only when a user needs to choose from about seven to 15 possible options and you have limited space to display the options.

When to consider something else

  • If the list of options is very short. Use radio buttons instead.
  • If the list of options is very long. Let users type the same information into a text input that suggests possible options instead.
  • If you need to allow users to select more than one option at once. Users often don’t understand how to select multiple items from select boxes. Use checkboxes instead.
  • If you are intending to provide navigation. To help users navigate to a section on the same page or another page in the site, use a text link or the sidenav component.

How to use

  • Test select boxes thoroughly with members of your target audience. Several usability experts suggest they should be the “UI of last resort.” Many users find them confusing and difficult to use.
  • On mobile devices, select boxes use a scroll wheel rather than a dropdown, which some users find difficult to use.
  • Avoid making options in one select box menu change based on the input to another. Users often don’t understand how selecting an item in one impacts another.
  • When most users will (or should) pick a particular option, make it the default: <option selected="selected">Default</option>
  • Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Offer a “submit” button at the end of the form instead. Users often change their choices multiple times. Auto-submission is also less accessible.

Errors

This is the error message
<div class="usa-input-error">
  <label class="usa-input-error-label" for="select-159">select label</label>
  <span class="usa-input-error-message" id="select-159-error-message" role="alert">This is the error message</span>
  <select aria-describedby="select-159-error-message" id="select-159" name="Attribute name">
    <option value=""></option>
    <option value="first option">first option</option>
    <option value="second option">second option</option>
    <option value="third option">third option</option>
  </select>
</div>
  • For select the error message does not include the screen reader-only “Error” text.
  • See form error handling for additional guidance.
<span class="usa-input-error-message" id="select-159-error-message" role="alert">This is the error message</span>

Native Events

  • The native onKeyDown event is available on this component. It can be used by adding the event handler to your component and it will then listen to the event and respond accordingly when the event fires.

Code usage

Attributes and Properties

Property Attribute Type Default Description
enableAnalytics enable-analytics boolean false Whether or not to fire the analytics events
error error string Error message to display. When defined, this indicates an error.
invalid invalid boolean false Whether or not `aria-invalid` will be set on the inner select. Useful when composing the component into something larger, like a date component.
label label string Text label for the field.
name name string Name attribute for the select field.
required required boolean false Whether or not this is a required field.
value value string Selected value (will get updated on select).

Events

Name Description
component-library-analytics The event used to track usage of the component. This is emitted when an option is selected and enableAnalytics is true.
vaKeyDown The event attached to select's onkeydown
vaSelect The event emitted when the selected value changes

Accessibility considerations

  • Make sure your select box has a label. Don’t replace it with the default menu option (for example, removing the “State” label and just having the dropdown read “Select a state” by default).
  • Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.
Edit this page in GitHub (Permissions required)
Last updated: Jun 14, 2022