Version 5.0.0

Picker

Pickers (sometimes known as dropdowns or selects) 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 pickers in open and closed states. Picker in closed state, label Transition selected value None. Picker 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 picker in its open state, including its label, required asterisk, field button, chevron, and menu.

Options#


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

Label#

Pickers 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 pickers 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 picker with placeholder text. A picker 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 picker with a placeholder. A picker 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 picker with a selected value. A picker 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 picker with customized width, showing two pickers of different widths.

Width#

The width of a picker can be customized appropriately for its context. This option is not applicable to quiet pickers.

Key example comparing a non-quiet and a quiet picker.

Quiet#

By default, pickers 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 pickers 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 pickers. A picker in the closed state with the label Country (optional) and placeholder text Select a country, followed by ellipsis. A picker in the closed state with the label Country (required) and placeholder text Select a country, followed by ellipsis. A picker in the closed state with the label Country and an asterisk and placeholder text Select a country, followed by ellipsis.

Required or optional#

Pickers can be marked as optional or required, depending on the situation. For required pickers, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional pickers are either denoted with text added to the end of the label — “(optional)” — or have no indication at all.

The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself.

A key example of a picker 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 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 picker with an error.  A picker 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 picker 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 picker.  A picker in the closed, disabled state with the label Page template and a selected value of Home.

Disabled#

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

Key example of read-only pickers. Label, Preferred contact method. Selected value, Email. Picker shows visual change when moused over, but text can still be selected.

Read-only#

Pickers have a read-only option for when content in the disabled state still needs to be shown. This allows for content to be copied, but not interacted with or changed.

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
Not applicable to quiet picker.
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
is read-only
yes / no
no

Behaviors#


Key example of regular and quiet pickers illustrating the minimum width. A regular picker with the label State and the selected value of CA. A quiet picker with the label State and the selected value of CA.

Minimum width#

The minimum width for a picker is 2× the height of the field button. This guarantees that small pickers are readable and easy to target on touch devices. Quiet pickers 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 picker should have a label. A picker without a label is ambiguous and not accessible.

Key example showing the correct usage of a picker label. A picker with the label Country of birth and the selected value of United States.
Key example showing the correct usage of a picker without a label. A picker 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 picker without a label. A quiet picker 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 picker menu item text length. A picker 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 picker menu item text length. A picker 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 picker. A picker with the label Country and the selected value of United States of America.
Key example showing the a picker with incorrect width. A picker 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 picker with correct sentence case capitalization. A picker with the label Country of birth and the placeholder text Select a country followed by ellipsis.
A key example of a picker with incorrect title case capitalization. A picker with the label Country of Birth and the placeholder text Select a Country followed by ellipsis.

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

In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. If most of the pickers are optional, only the required fields should be give an asterisk or have labels appended with “(required)”. If most of the pickers are required, only the optional fields should be appended with “(optional)”. An asterisk should never be used to note that a picker is optional.

A key example showing correct usage of required and optional pickers. A picker with the label View by and the placeholder text Select an option followed by ellipsis. A picker with the label View by and the placeholder text Select an option followed by ellipsis. A picker 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 pickers. A picker with the label View by (required) and the placeholder text Select an option followed by ellipsis. A picker with the label View by (required) and the placeholder text Select an option followed by ellipsis. A picker with the label Country and the placeholder text Select an option followed by ellipsis.

Internationalization#


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

RTL#

For RTL (right-to-left) languages, the layout of the picker 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
Apr 23, 20206.0.0
  • "Dropdown" has been renamed to "picker"
Feb 25, 20195.2.0
  • Added read-only option
  • Updated border color to be more accessible
Aug 21, 20185.1.0
  • Added text overflow behavior
Aug 12, 20185.0.1
  • Changed selected item text color from blue 500 to gray 800
Apr 18, 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.

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