Version 5.1.0

Dropdown

Dropdowns allow users to choose from a list of options in a limited space. The list of options can change based on the context.

Image illustrating dropdowns in open and closed states. Dropdown in closed state, label Transition selected value None. Dropdown in open state, label Easing, selected value Ease out, other menu options Ease in, Ease out, Ease in-out, None.

Anatomy#


Image illustrating through labels the component parts of a dropdown in its open state, including its label, required asterisk, field button, chevron, and menu.

Options#


Key example of a dropdown with a label. A dropdown in the closed state with the label Country and placeholder text Select a country, followed by ellipsis.

Label#

Dropdowns should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These dropdowns without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”).

Key example of a dropdown with placeholder text. A dropdown in the closed state with the label Country and placeholder text Select a country, followed by ellipsis.

Label position#

Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited.

Key example of a dropdown with a placeholder. A dropdown in the closed state with the label Country and placeholder text Select a country, followed by ellipsis.

Placeholder#

The placeholder text, also commonly known as “ghost text,” is temporary and disappears once a user selects an option.

Key example of a dropdown with a selected value. A dropdown in the closed state with the label Country and a selected value of United States.

Value#

The value shows the option that a user has selected.

Key example of a dropdown with customized width, showing two dropdowns of different widths.

Width#

The width of a dropdown can be customized appropriately for its context.

Key example comparing a standard dropdown and a quiet dropdown.

Quiet#

By default, dropdowns have a visible background. This style works best in a dense array of controls where the background helps to separate the input from the surrounding container, or to give visibility to isolated buttons.

Alternatively, quiet dropdowns can have no visible background. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read.

Key example of optional and required dropdowns. A dropdown in the closed state with the label Country (optional) and placeholder text Select a country, followed by ellipsis. A dropdown in the closed state with the label Country (required) and placeholder text Select a country, followed by ellipsis. A dropdown in the closed state with the label Country and an asterisk and placeholder text Select a country, followed by ellipsis.

Required or optional#

Dropdowns can be marked as optional or required, depending on the situation. For required dropdowns, there are two styling options: a “(required)” label or an asterisk. Make sure to include hint text to explain what the asterisk means.

A key example of a dropdown in the open state displayed on a mobile device. The menu is displayed in a tray at the bottom of the device's screen.

On mobile, the dropdown menu can be exposed in either a popover or a tray. Use a tray when the number of options is too overwhelming for a popover.

Key example of a dropdown with an error.  A dropdown in the closed state with the label Page template and a selected value of Home, with a red border and an alert icon indicating an error.

Error#

A dropdown can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid.

Key example of a disabled dropdown.  A dropdown in the closed, disabled state with the label Page template and a selected value of Home.

Disabled#

A dropdown in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Value
label
text / nothing
label position
top / side
top
placeholder
text
value
text / nothing
width
number
is quiet
yes / no
no
necessity indicator
text / icon / nothing
icon
is required
yes / no
no
menu container
popover / tray
The option to display the menu in a tray is available on mobile devices only.
popover
is error
yes / no
no
is disabled
yes / no
no

Behaviors#


Key example of standard and quiet dropdowns illustrating the minimum width. A standard dropdown with the label State and the selected value of CA. A quiet dropdown with the label State and the selected value of CA.

Minimum width#

The minimum width for a standard dropdown is 2× the height of the field button. This guarantees that small dropdowns are readable and easy to target on touch devices. Quiet dropdowns do not have a minimum width; their width depends on the length of the text.

Key example of text overflow behavior in a dropdown. A label with the wrapping text Select the size you want this export to be. A dropdown with the truncated selected value of Large select this followed by ellipsis. A menu with the wrapping text Small works best for mobile phones.

Text overflow#

When the field label and menu text are too long for the available horizontal space, they wrap to form another line. The field text itself truncates at the end, but the text can be shown in full in the menu.

Usage guidelines#


Include a label#

Every dropdown should have a label. A dropdown without a label is ambiguous and not accessible.

Key example showing the correct usage of a dropdown label. A dropdown with the label Country of birth and the selected value of United States.
Key example showing the correct usage of a dropdown without a label. A dropdown with no label and the selected value of United States.

Review label-less designs#

In rare cases where context is sufficient and a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. These should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”).

Key example showing the correct usage of a dropdown without a label. A quiet dropdown with the selected value of Sort by date.

Keep menu items concise#

Keep menu items short and concise. Long menu items that cause text to wrap to multiple lines are discouraged. If text wrapping becomes a frequent concern, consider revising the text or use alternative UI patterns that will give your content more space.

A key example showing correct dropdown menu item text length. A dropdown in the open state with the label size and placeholder text Select an option followed by ellipsis, a menu with the items Small, Medium, and Large.
A key example showing incorrect dropdown menu item text length. A dropdown in the open state with the label size and placeholder text Select an option followed by ellipsis, a menu with the items Small (works best for mobile phones), Medium (all-purpose), and Large (select this one for printing).

Choose an appropriate width#

When possible, the field button width should be wide enough so that any chosen menu items can be displayed in full.

Key example showing the correct width of a dropdown. A dropdown with the label Country and the selected value of United States of America.
Key example showing the a dropdown with incorrect width. A dropdown with the label Country and the selected value of United Sta followed by ellipsis.

Follow capitalization rules#

Field labels, placeholder text, and menu items should be in sentence case.

A key example of a dropdown with correct sentence case capitalization. A dropdown with the label Country of birth and the placeholder text Select a country followed by ellipsis.
A key example of a dropdown with incorrect title case capitalization. A dropdown with the label Country of Birth and the placeholder text Select a Country followed by ellipsis.

Mark the minority of dropdowns in a form as optional or required#

In a single form, mark just the required fields or just the optional fields, depending on whichever mention is less frequent. For required dropdowns, there are two styling possibilities: a “(required)” label or an asterisk. Make sure to include some hint text at the end of the form to explain what the asterisk means.

A key example showing correct usage of required and optional dropdowns. A dropdown with the label View by and the placeholder text Select an option followed by ellipsis. A dropdown with the label View by and the placeholder text Select an option followed by ellipsis. A dropdown with the label Country (optional) and the placeholder text Select an option followed by ellipsis.
A key example showing incorrect usage of required and optional dropdowns. A dropdown with the label View by (required) and the placeholder text Select an option followed by ellipsis. A dropdown with the label View by (required) and the placeholder text Select an option followed by ellipsis. A dropdown with the label Country and the placeholder text Select an option followed by ellipsis.

Internationalization#


Key example of dropdown internationalization for right-to-left languages. Layout of dropdown is mirrored, label and menu items are in Arabic.

RTL#

For RTL (right-to-left) languages, the layout of the dropdown is mirrored. Text is right-aligned while the chevron and checkmark are left-aligned.

Keyboard interactions#


When the popover menu is closed:

KeyInteraction
Space or Down ArrowOpens the popover menu. The focus is set on the menu item selected.

When the popover menu is open:

KeyInteraction
SpaceSelects the menu item in focus, closes the popover menu and moves focus to the field button.
Up or Down ArrowMoves focus to previous or next menu item in the popover. Does not loop when the last or first menu item is reached.
EscCloses the popover menu and moves focus to the field button.

Changelog#


DateNumberNotes
Aug 22, 20195.1.0
  • Added text overflow behavior
Aug 13, 20195.0.1
  • Changed selected item text color from blue 500 to gray 800
Apr 19, 20195.0.0
  • This component is now individually versioned (individual versions of existing components start at 5.0.0)
  • Added RTL (right-to-left) guidelines

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Downloadable UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.