Examples

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.

Styles

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

Text Input Options

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

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 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.

Related patterns

• Checkbox and Radio
• Text field

Learn more

• Form Guidelines
• Asking for a date of birth
• Four steps for choosing form elements on the Web (PDF)
• Dropdowns: Design Guidelines

Component maturity