Skip to main content

An official website of the United States government

Here's how you know

An official website of the United States government

Here's how you know

Theme:

Design system switcher

Version:

Design system switcher

Theme:

Design system switcher

Version:

Design system switcher

Dropdown

Dropdowns allow users to select one option from a temporary modal menu.

Examples

Loading

Code

React

Note that any undocumented props that you pass to this component will be passed to the select element, so you can use this to set additional attributes if necessary.

See Storybook for React guidance of this component.

Style customization

The following CSS variables can be overridden to customize Dropdown components:

CSS variables for dropdown
VariableDefault Core Theme Value
--dropdown__background-colorhex value: #ffffff--color-white
--dropdown-option-group__padding24px

Text Input Options

This component also makes use of some text input styles, which can be customized by the following variables:

CSS variables for text-input
VariableDefault Core Theme Value
--text-input__line-height1.3
--text-input__background-color--disabledhex value: #d9d9d9--color-border
--text-input__border-width2px
--text-input__border-width--error3px
--text-input__border-colorhex value: #262626--color-base
--text-input__border-color--disabledhex value: #a6a6a6--color-gray-light
--text-input__border-color--errorhex value: #e31c3d--color-error
--text-input__border-color--error--inversehex value: #f7bbc5--color-error-lighter
--text-input__border-color--inversehex value: #000000--color-black
--text-input__colorhex value: #262626--color-base
--text-input__divider-colorhex value: #a6a6a6--color-gray-light
--text-input__padding8px
--text-input__border-radius3px

Guidance

When to use

  • Use sparingly. Use the dropdown component 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 alternatives

  • Fewer than seven options. Use radio buttons or checkboxes instead.
  • More than 15 options. If the list of options is very long. Let users type the same information into a text input that suggests possible options instead.
  • Multi-select. 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 dropdowns. Use checkboxes instead.
  • Site navigation. Use the navigation components instead.

Usage

  • Always use a label. Make sure your dropdown 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).
  • Make sure to test. Test dropdowns 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.
  • Use a good default. When most users will (or should) pick a particular option, make it the selected default. If a good default is not an option, use a descriptive placeholder like - Select a state - as the selected default.
  • Avoid using dropdown to change context. Don't automatically change content on the page or navigate when a user selects a different value. According to WCAG 2.1, you should warn users if changing a form control changes context.
  • Avoid dependent options. Avoid making options in one dropdown menu change based on the input to another. Users often don’t understand how selecting an item in one impacts another.
  • Order alphabetically. Present the options in alphabetical order as the default ordering when possible.

View the "Forms" guidelines for additional guidance and best practices.

Accessibility

Accessibility testing

General observations
  • The dropdown list should be closed by default.
  • When the dropdown list is displayed, aria-expanded is set to true and, conversely, set to false when the listbox is closed.
  • The dropdown button contains aria-haspopup="listbox", while the listbox contains a role="listbox".
  • The dropdown button contains an aria-controls attribute which maps to an id on the listbox.
  • Selected option text that is longer than the dropdown button will be truncated, but the full text of that option will be displayed on multiple lines in the dropdown list.
Keyboard testing
  • When the Dropdown is closed and has focus
    • Users can open the listbox by pressing Space, Enter, Down, Up, Alt + Up or Alt + Down. When the listbox opens it highlights the current option
    • If a user begins typing then the listbox will open and will highlight the first option that matches the typed character.
    • If the same character is typed in succession, visual focus cycles among the options starting with that character.
  • When the Dropdown is open
    • Escape key closes the options, sets visual focus on the combobox, and retains the current value.
    • Up and Down keys should cycle through options.
    • Enter key selects the currently focused option and closes the menu.
    • Space key selects the currently focused option and closes the menu.
    • If the same character is typed in succession, visual focus cycles among the options starting with that character.
    • Home key moves visual focus to the first option.
    • End key moves visual focus to the last option.
Screen reader testing
  • When I navigate to the Dropdown
    • If hints or errors are present, they are read.
  • When the listbox is displayed
    • I use the arrow keys to select an option and I hear the selected option is changed.
    • I select an option with the Enter or Space key and hear the selected option.
Mobile screen reader testing
  • I can swipe to focus on the component.
  • I can hear the purpose of the element.
  • It identifies itself as a combobox.
  • I hear hints or errors are read.
  • I hear it indicate which option is selected.
Pointer device testing
  • I select anywhere inside the the dropdown button to display or hide the listbox.
  • I select an option by clicking anywhere inside the option list.
  • I select an option and the aria-selected attribute is added to the currently selected option.
  • If using a mouse, a hover state (highlighted state) is visible over each non-selected list options as I drag the mouse over them.
  • I select an option and that option is displayed in the dropdown component and the listbox is hidden.
  • I select anywhere outside the component to close the listbox when it is displaying.

Learn more

Component maturity

Because Dropdown is now a custom built solution using Adobe Spectrum instead of a native <select> element, Axe flags the use of a hidden input as a false positive. This is a known issue but not considered a problem.

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Incomplete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Not applicable

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete