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.
Additional classes to be added to the root element.
Used to define custom dropdown options (i.e. option groups). When using the
Sets the initial selected state. Use this for an uncontrolled component;
otherwise, use the
Disables the entire field.
Additional classes to be added to the error message
Location of the error message relative to the field input
Additional classes to be added to the select element
Used to focus
Additional hint text to display
A unique ID to be used for the dropdown field. If one isn't provided, a unique ID will be generated.
Access a reference to the
Applies the "inverse" UI theme
Label for the field. If using
Additional classes to be added to the
The list of options to be rendered. Provide an empty list if using custom options via the
Text showing the requirement ("Required", "Optional", etc.). See Required and Optional Fields.
If the component renders a select, set the max-width of the input either to
Sets the field's
The following Sass variables can be overridden to customize Dropdown components:
This component also makes use of some text input styles, which can be customized by the following variables:
- 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.
- 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.
- 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.
- 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).
- [Form Guidelines]/guidelines/forms/)
- Asking for a date of birth
- Four steps for choosing form elements on the Web (PDF)
- Dropdowns: Design Guidelines
For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.
ColorMeets 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 ConformanceAll Axe checks for WCAG AA compliance have passed.Complete
Screen readersVoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.Complete
Keyboard navigationComponent is fully navigable with a keyboard.Complete
StorybookComponent has stories to cover all defined props.Complete
ResponsiveComponent designed to work in all responsive breakpoints.Complete
Spanish translationsIncludes Spanish translations for default text content.Not applicable
CodeTokens implemented in code.Complete
DesignTokens implemented in the Sketch.Complete