No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

The component failed to render properly, likely due to a configuration issue in Storybook. Here are some common causes and how you can address them:

  1. Missing Context/Providers: You can use decorators to supply specific contexts or providers, which are sometimes necessary for components to render correctly. For detailed instructions on using decorators, please visit the Decorators documentation.
  2. Misconfigured Webpack or Vite: Verify that Storybook picks up all necessary settings for loaders, plugins, and other relevant parameters. You can find step-by-step guides for configuring Webpack or Vite with Storybook.
  3. Missing Environment Variables: Your Storybook may require specific environment variables to function as intended. You can set up custom environment variables as outlined in the Environment Variables documentation.

Picker

Local version:
10.0.0-next.1 unpublished

Design guidelines

Spectrum website

Web components

Spectrum web components

View package

npm

View repository

GitHub

The picker component (sometimes known as a "dropdown" or "select") allows users to choose from a list of options in a limited space. The list of options can change based on the context.

Variants

Default

The following example shows the picker with both a field label and placeholder text. Pickers should always have a label. The placeholder text can be displayed when it does not have a selected value.

Closed
Open

Default with value and help text

This example shows the picker with a selected value. A picker can also have help text below the field to give extra context or instruction about what a user should select.

Closed
Additional field context
Open
Additional field context

Disabled

Default
Invalid

Invalid

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. This example shows the optional error message within the help text area.

Closed
Select a country.
Open
Select a country.

Loading

Quiet

Quiet pickers 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.

Closed
Open

Quiet and disabled

Default
Invalid

Quiet and invalid

Closed
Select a country.
Open
Select a country.

Sizing

Pickers come in four different sizes: small, medium, large, and extra-large.

At each of these sizes, the following chevron UI icon should be used:

Picker sizeUI icon size
smallChevron75
mediumChevron100
largeChevron200
extra-largeChevron300
Small
Medium
Large
Extra-large

Text overflow

The value and placeholder within the picker will truncate with an ellipsis when it is longer than the available horizontal space within the picker. The full text of the option can be shown in the menu.

With side label

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.

When using the side label, the spectrum-Picker--sideLabel class is added to the Picker.

With workflow icon

A workflow icon can be displayed before the value or placeholder. The class .spectrum-Picker-icon should be used with the icon.

Properties

The component accepts the following inputs (properties):

NameDescriptionDefault
Component
Size*
string
-
Label position
string
-
Quiet styling
An alternative way to display the Picker without a visible background.
boolean
-
Content
Label
The label text that is displayed above or to the side of the Picker. This uses a separate Label component outside of the Picker markup.
string
-
Value or placeholder
The text within the Picker that represents its current value or placeholder.
string
-
Help text
Optional help text that can be informational or an error message. Displays a separate help text component after the picker. For error messages, the invalid control must also be set to true.
string
-
Icon
Optional workflow icon that appears before the value/placeholder text within the picker.
string
-
Advanced
Show workflow icon
Display optional workflow icon before the value or placeholder
boolean
-
State
Keyboard Focused
boolean
-
Disabled
boolean
-
Invalid
When in the invalid state, some styles change on the Picker, and an invalid icon displays next to the disclosure icon.
boolean
-
Open
boolean
-
Hovered
boolean
-
Active
boolean
-

Modifiable custom properties

These are empty CSS custom property hooks available in this component that enable one-off customizations specific to a product implementation.

Property
--mod-picker-animation-duration
--mod-picker-background-color-active
--mod-picker-background-color-default
--mod-picker-background-color-default-open
--mod-picker-background-color-disabled
--mod-picker-background-color-hover
--mod-picker-background-color-hover-open
--mod-picker-background-color-key-focus
--mod-picker-block-size
--mod-picker-border-active
--mod-picker-border-color-default
--mod-picker-border-color-error-active
--mod-picker-border-color-error-default
--mod-picker-border-color-error-default-open
--mod-picker-border-color-error-hover
--mod-picker-border-color-error-hover-open
--mod-picker-border-color-error-key-focus
--mod-picker-border-color-hover
--mod-picker-border-color-hover-open
--mod-picker-border-color-key-focus
--mod-picker-border-default-open
--mod-picker-border-radius
--mod-picker-border-width
--mod-picker-focus-indicator-color
--mod-picker-focus-indicator-gap
--mod-picker-focus-indicator-thickness
--mod-picker-font-color-active
--mod-picker-font-color-default
--mod-picker-font-color-default-open
--mod-picker-font-color-disabled
--mod-picker-font-color-hover
--mod-picker-font-color-hover-open
--mod-picker-font-color-key-focus
--mod-picker-font-size
--mod-picker-font-weight
--mod-picker-icon-color-active
--mod-picker-icon-color-default
--mod-picker-icon-color-default-open
--mod-picker-icon-color-disabled
--mod-picker-icon-color-error
--mod-picker-icon-color-hover
--mod-picker-icon-color-hover-open
--mod-picker-icon-color-key-focus
--mod-picker-inline-size
--mod-picker-inline-size-quiet
--mod-picker-line-height
--mod-picker-line-height-cjk
--mod-picker-min-inline-size
--mod-picker-min-inline-size-quiet
--mod-picker-placeholder-font-style
--mod-picker-placeholder-font-weight
--mod-picker-spacing-bottom-to-text
--mod-picker-spacing-edge-to-disclosure-icon
--mod-picker-spacing-edge-to-disclosure-icon-quiet
--mod-picker-spacing-edge-to-text
--mod-picker-spacing-edge-to-text-quiet
--mod-picker-spacing-icon-to-disclosure-icon
--mod-picker-spacing-label-to-picker
--mod-picker-spacing-label-to-picker-quiet
--mod-picker-spacing-picker-to-popover
--mod-picker-spacing-starting-icon-to-text
--mod-picker-spacing-text-to-icon-inline-end
--mod-picker-spacing-top-to-alert-icon
--mod-picker-spacing-top-to-disclosure-icon
--mod-picker-spacing-top-to-progress-circle
--mod-picker-spacing-top-to-text

Tagged releases

latest
9.1.4
next
10.0.0-next.1
s2-foundations
9.0.0-s2-foundations.17
beta
7.0.0-beta.0