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

select label 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.
`hint`	`hint`	`string`		Optional hint text.
`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.
`uswds`	`uswds`	`boolean`	`false`	Whether or not the component will use USWDS v3 styling.
`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.