Skip to main content
U.S. Flag

An official website of the United States government

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.

React Properties Documentation
NameTypeDefaultDescription
ariaLabelstringAdds aria-label attribute. When using aria-label, label should be empty string.
childrenReactNodeUsed to define custom dropdown options (i.e. option groups). When using the children prop, options should be an empty list.
defaultValueDropdownDefaultValueSets the initial selected state. Use this for an uncontrolled component; otherwise, use the value property.
disabledbooleanDisables the entire field.
fieldClassNamestringAdditional classes to be added to the select element
autoFocusbooleanSets the focus on the select during the first mount
idstringA unique ID to be used for the select element. If one isn't provided, a unique ID will be generated. /** Additional hint text to display
inputRef(...args: any[]) => anyAccess a reference to the select element
inversedbooleanApplies the "inverse" UI theme
namerequiredstringThe field's name attribute
optionsrequiredDropdownOptions[]The list of options to be rendered. Provide an empty list if using custom options via the children prop.
onBlur(...args: any[]) => any
onChange(...args: any[]) => any
requirementLabelReactNodeText showing the requirement ("Required", "Optional", etc.). See Required and Optional Fields.
sizeDropdownSizeSets the max-width of the input either to 'small' or 'medium'.
valueDropdownValueSets the field's value. Use this in combination with onChange for a controlled component; otherwise, set defaultValue.
classNamestringAdditional classes to be added to the root element.
labelrequiredReactNodeLabel for the field.
labelIdstringA unique id to be used on the field label. If one isn't provided, a unique ID will be generated.
errorMessageReactNodeEnable the error state by providing an error message.
errorMessageClassNamestringAdditional classes to be added to the error message
errorIdstringThe ID of the error message applied to this field.
hintReactNodeAdditional hint text to display
textClassNamestringAdditional classes to be added to the label text.
errorPlacement"top" | "bottom"Location of the error message relative to the field input
labelClassNamestringAdditional classes to be added to the field label

Styles

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__icon-size10px

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-width--success3px
--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: #f18e9e--color-error-light
--text-input__border-color--inversehex value: #000000--color-black
--text-input__border-color--successhex value: #2a9526--color-green-light
--text-input__colorhex value: #262626--color-base
--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

  • 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.
  • 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.
  • 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 auto-submission. 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.

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

Accessibility

  • Customize accessibly. If you customize the dropdown, ensure it continues to meet the the accessibility requirements that apply to all form controls.
  • 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).
  • Avoid auto-submission. 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.

Learn more

Component maturity

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