Skip to main content

U.S. flagU.S. flag

An official website of the United States government

CMS Design System

CMS Design System v2 is released!  See our migration guide.

Dropdown

Jump to guidance View related guidance in the U.S. Web Design System

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

Code snippet
<div>
  <label class="ds-c-label ds-u-margin-top--0" for="options"><span>Dropdown example</span></label>
  <select class="ds-c-field" name="options" id="options">
    <option value="">- Select an option -</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <option value="3">Option 3</option>
    <option value="4">Option 4</option>
    <option value="5">Option 5</option>
    <option value="6">Option 6</option>
    <option value="7">Option 7</option>
  </select>
</div>
<div class="example--wrapper example--inverse">
  <div>
    <label class="ds-c-label ds-u-margin-top--0" for="options-inverse">
      <span>Inverse example</span>
      <span class="ds-c-field__hint ds-c-field__hint--inverse">
        Helpful hint text
      </span>
      <span class="ds-c-field__error-message ds-c-field__error-message--inverse" role="alert">
        Example error message
      </span>
    </label>
    <select
      class="ds-c-field ds-c-field--error ds-c-field--inverse"
      name="options-inverse"
      id="options-inverse"
    >
      <option value="">- Select an option -</option>
      <option value="1">Option 1</option>
      <option value="2">Option 2</option>
      <option value="3">Option 3</option>
      <option value="4">Option 4</option>
      <option value="5">Option 5</option>
      <option value="6">Option 6</option>
      <option value="7">Option 7</option>
    </select>
  </div>
</div>
React

<Dropdown>

View source file

A Dropdown component can be used to render an HTML select menu. 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.

Class-based component gives flexibility for active focus management by allowing refs to be passed.

Code snippet
const dropdownOptions = [
  { label: '- Select an option -', value: '' },
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' },
  { label: 'Option 3', value: '3' },
  { label: 'Option 4', value: '4' },
  { label: 'Option 5', value: '5' },
  { label: 'Option 6', value: '6' },
  { label: 'Option 7', value: '7' },
  { label: 'Option 8', value: '8' },
];

ReactDOM.render(
  <div className="example--wrapper">
    <Dropdown
      options={dropdownOptions}
      defaultValue=""
      label="Dropdown example"
      labelClassName="ds-u-margin-top--0"
      name="dropdown_field"
    />
    <Dropdown
      options={dropdownOptions}
      defaultValue=""
      size="small"
      label="Small size example"
      name="small_dropdown_field"
    />
    <Dropdown
      options={dropdownOptions}
      defaultValue=""
      size="medium"
      label="Medium size example"
      name="medium_dropdown_field"
    />
    <Dropdown
      options={dropdownOptions}
      defaultValue=""
      errorMessage="Example error message"
      hint="Helpful hint text"
      label="Error example"
      name="error_dropdown_field"
    />
    <Dropdown
      options={dropdownOptions}
      defaultValue=""
      label="Disabled example"
      disabled
      name="disabled_dropdown_field"
    />
    <Dropdown
      options={[]}
      defaultValue="1-1"
      label="Option group example"
      name="custom_dropdown_field"
    >
      <optgroup label="Option group">
        <option value="1-1">Option 1</option>
        <option value="1-2">Option 2</option>
        <option value="1-3">Option 3</option>
      </optgroup>
      <optgroup label="More option groups">
        <option value="2-1">Option 4</option>
        <option value="2-2">Option 5</option>
        <option value="2-3">Option 6</option>
      </optgroup>
    </Dropdown>
    <div className="example--wrapper example--inverse">
      <Dropdown
        labelClassName="ds-u-margin-top--0"
        options={dropdownOptions}
        defaultValue=""
        errorMessage="Example error message"
        hint="Helpful hint text"
        label="Inverse example"
        name="inverse_dropdown_field"
        inversed
      />
    </div>
  </div>,
  document.getElementById('js-example')
);

Props

React Properties Documentation
NameTypeDefaultDescription
ariaLabelstring

Adds aria-label attribute. When using aria-label, label should be empty string.

classNamestring

Additional classes to be added to the root element.

childrenstring, number, element, or array

Used to define custom dropdown options (i.e. option groups). When using the children prop, options should be an empty list.

defaultValuenumber, string

Sets the initial selected state. Use this for an uncontrolled component; otherwise, use the value property.

disabledbool

Disables the entire field.

errorMessagestring, number, element, or array
errorMessageClassNamestring

Additional classes to be added to the error message

errorPlacement'top', 'bottom'

Location of the error message relative to the field input

fieldClassNamestring

Additional classes to be added to the select element

focusTriggerbool

Used to focus select on componentDidMount()

hintstring, number, element, or array

Additional hint text to display

idstring

A unique ID to be used for the dropdown field. If one isn't provided, a unique ID will be generated.

inputReffunc

Access a reference to the select element

inversedbool

Applies the "inverse" UI theme

label

Required

string, number, element, or array

Label for the field. If using Dropdown without a label, provide an empty string for label and use the ariaLabel prop instead.

labelClassNamestring

Additional classes to be added to the FormLabel.

name

Required

string

The field's name attribute

options

Required

arrayOf[{label, value}]

The list of options to be rendered. Provide an empty list if using custom options via the children prop.

onBlurfunc
onChangefunc
requirementLabelstring, number, element, or array

Text showing the requirement ("Required", "Optional", etc.). See Required and Optional Fields.

size'small', 'medium'

If the component renders a select, set the max-width of the input either to 'small' or 'medium'.

valuenumber, string

Sets the field's value. Use this in combination with onChange for a controlled component; otherwise, set defaultValue.

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.

Related patterns

Learn more