Components

Select

Use: Deployed English, Spanish

USWDS v3

A select component allows users to choose one option from a menu.

Examples

Usage

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

Additional guidance for VA

Additional reasons to consider something else

More than 15 options. If the list of options is very long, we do not yet have the combo box component in our system thus an alternative is to use functionality that allows users to type the same information into a text input that suggests possible options instead as seen in our search input component.

Errors

Refer to the specific error example above.

View form error handling for additional guidance

Hint text

Refer to the hint text example above.

View label hint text for additional guidance

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.
`messageAriaDescribedby`	`message-aria-describedby`	`string`		An optional message that will be read by screen readers when the select is focused.
`name`	`name`	`string`		Name attribute for the select field.
`reflectInputError`	`reflect-input-error`	`boolean`	`false`	Whether or not to add usa-input--error as class if error message is outside of component
`required`	`required`	`boolean`	`false`	Whether or not this is a required field.
`showError`	`show-error`	`boolean`	`true`	Whether an error message should be shown - set to false when this component is used inside va-date or va-memorable-date in which the error for the va-select will be rendered outside of va-select
`value`	`value`	`string`		Selected value (will get updated on select).
`width`	`width`	`string`		Displays the select at a specific width. Accepts 2xs (4ex), xs (7ex), sm or small (10ex), md or medium (20ex), lg (30ex), xl (40ex), and 2xl (50ex).

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

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.

Accessibility considerations

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

Component checklist

Maturity

Guidance: Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research: VFS team conducted research on this component which is linked from this page.
Stability: Component has been in production for more than 3 months with no significant issues found.
Adoption: Multiple teams have adopted this component.

Accessibility

While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

Code assets

Variations: Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component depicted in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.
Internationalization: Describes i18n attributes.

Visual assets

Variations: Sketch library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component designed to work in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.

100% complete (11 of 11)

Legend:

Complete
Incomplete
Not applicable

Select

Examples

Default

Required

With hint text

Read only

Error

Dynamic options

Internationalization

Widths