sp-picker

size Small Medium Large Extra large
quiet true false
disabled true false
invalid true false

NPM

1.1.2

Storybook

View Storybook

Try it on

webcomponents.dev
Examples API Changelog

1.1.2 (2025-02-12) #

Bug Fixes #

  • overlay: derive popover placement from host in interaction controller (#5078) (635cf53)
  • picker: stop the click events from reaching the elements below picker-tray (#5060) (7e4fdbf)

1.1.1 (2025-01-29) #

Bug Fixes #

  • overlay: make :focus-visible consistent when using overlay type modal (#4912) (7a5f786), closes #5021

Features #

  • picker: add forcePopover property (#5041) (3651e57)

1.1.0 (2025-01-29) #

Bug Fixes #

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)
  • overlay: make :focus-visible consistent when using overlay type modal (#4912) (7a5f786), closes #5021

Features #

  • add an optional chromatic vrt action (7d2f840)
  • picker: add forcePopover property (#5041) (3651e57)

1.0.3 (2024-12-09) #

Note: Version bump only for package @spectrum-web-components/picker

1.0.1 (2024-11-11) #

Bug Fixes #

  • picker: don't handle pointerdown for touch devices (#4850) (3a62d13)

1.0.0 (2024-10-31) #

Note: Version bump only for package @spectrum-web-components/picker

0.49.0 (2024-10-15) #

Note: Version bump only for package @spectrum-web-components/picker

0.48.1 (2024-10-01) #

Note: Version bump only for package @spectrum-web-components/picker

0.48.0 (2024-09-17) #

Bug Fixes #

  • action-menu: dispatch scroll event (#4715) (c76f3f5)
  • picker: added a custom class to make :focus-visible styles consistent across all browsers (#4724) (d667d08)

Features #

  • reactive-controller: new pending state controller (#4605) (68baf94)

0.47.2 (2024-09-03) #

Note: Version bump only for package @spectrum-web-components/picker

0.47.1 (2024-08-27) #

Note: Version bump only for package @spectrum-web-components/picker

0.47.0 (2024-08-20) #

Bug Fixes #

  • picker: updated type for mobile and desktop (#4666) (d11da1f)

0.46.0 (2024-08-08) #

Note: Version bump only for package @spectrum-web-components/picker

0.45.0 (2024-07-30) #

Bug Fixes #

  • picker pointerup in mobile does not automatically make a selection. (4227) ([56366ce] (https://github.com/adobe/spectrum-web-components/commit/56366ce2750bb4bb5c6e3fa5fe7d809434497adb))

Note: Version bump only for package @spectrum-web-components/picker

0.44.0 (2024-07-15) #

Features #

  • action-bar: support for action-menus (#3780) (4aff599)

0.43.0 (2024-06-11) #

Note: Version bump only for package @spectrum-web-components/picker

0.42.5 (2024-05-24) #

Note: Version bump only for package @spectrum-web-components/picker

0.42.4 (2024-05-14) #

Bug Fixes #

  • action-menu: allow menu groups to handle their own selections (#4397) (5a19051)

0.42.3 (2024-05-01) #

Note: Version bump only for package @spectrum-web-components/picker

0.42.2 (2024-04-03) #

Note: Version bump only for package @spectrum-web-components/picker

0.42.1 (2024-04-02) #

Note: Version bump only for package @spectrum-web-components/picker

0.42.0 (2024-03-19) #

Bug Fixes #

  • picker: add loading state to the picker (#3110) (d91e2c9)
  • picker: allow open/close in tablet (dcfc96e)
  • picker: correctly process the CSS for the quiet hover effect (#4167) (eb282fa)

Features #

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05) #

Bug Fixes #

  • overlay: leverage "transition-behavior" to persist top-layer content while closing (#4050) (e3dea14)
  • picker: support inline labeling of quiet Picker (#3704) (3372286)

0.41.1 (2024-02-22) #

Bug Fixes #

  • picker: correct implementation of "disabled", expand stories and documentation (#4040) (84c2fef)

0.41.0 (2024-02-13) #

Features #

  • icon: use core tokens (a11ef6b)

0.40.5 (2024-02-05) #

Note: Version bump only for package @spectrum-web-components/picker

0.40.4 (2024-01-29) #

Bug Fixes #

  • picker,action-menu,split-button: update interaction model (#3935) (bae7d52)

0.40.3 (2024-01-11) #

Bug Fixes #

  • picker: force close slotted Tooltip elements with disabled when Menu openes (82c8f12)
  • picker: prevent the Menu opening until required dependencies are loaded (55e6174)

0.40.2 (2023-12-18) #

Note: Version bump only for package @spectrum-web-components/picker

0.40.1 (2023-12-05) #

Bug Fixes #

  • picker: ensure menu placement in mobile (#3835) (4aba1c6)

0.40.0 (2023-11-16) #

Note: Version bump only for package @spectrum-web-components/picker

0.39.4 (2023-11-02) #

Bug Fixes #

  • overlay: calculate more transforms (6538a45)

0.39.3 (2023-10-18) #

Note: Version bump only for package @spectrum-web-components/picker

0.39.2 (2023-10-13) #

Note: Version bump only for package @spectrum-web-components/picker

0.39.1 (2023-10-06) #

Note: Version bump only for package @spectrum-web-components/picker

0.39.0 (2023-09-25) #

Bug Fixes #

  • picker,split-button: include "tooltip" slot in the main button (699b8af)

0.38.0 (2023-09-05) #

Bug Fixes #

  • action-menu,split-button: ensure toggling the Menu closed completes (2dd0f98)
  • picker: ensure the Menu opens in a Tray on mobile (6be2bed)

0.37.0 (2023-08-18) #

Bug Fixes #

  • allow non-selection carying Picker derivatives to report value (02c0134)

Features #

  • picker,action-group,split-button: leverage Overlay v2 (170a223)

Performance Improvements #

  • make lots of things lazy (b8fa3ad)
  • make submenus lazier (a2d661c)

0.36.0 (2023-08-18) #

Features #

  • menu: convert to core tokens (#3254) (da43540)

0.35.0 (2023-07-31) #

Note: Version bump only for package @spectrum-web-components/picker

0.34.0 (2023-07-11) #

Bug Fixes #

  • action-button,action-menu,picker,split-button: expand and update application of aria-* attributes (52c0156)
  • picker: correct label application for screen readers (8ce0cb0)

0.33.2 (2023-06-14) #

Note: Version bump only for package @spectrum-web-components/picker

0.33.1 (2023-06-14) #

Note: Version bump only for package @spectrum-web-components/picker

0.33.0 (2023-06-08) #

Note: Version bump only for package @spectrum-web-components/picker

0.32.0 (2023-06-01) #

Bug Fixes #

  • picker: correct attribute spelling of "aria-label" in dismiss button (5fc9b30)

0.31.0 (2023-05-17) #

Bug Fixes #

  • generate react/picker and pass react TS checks (101b88c)

0.30.0 (2023-05-03) #

Bug Fixes #

  • abstract "hasVisibleFocusInTree" functionality and return trigger focus after close (4f39f2c)
  • action-menu: fix 2510, unable to control top-level action-menu selection (c9198c2)
  • action-menu: never set item selected values when selects is undefined (5237fdb)
  • action-menu: stop stripping selected state from submenu items (968d1f2)
  • add icon present and icon-only support to Picker (f6887a3)
  • add support for "readonly" attribute (4bce3b7)
  • add t-shirt sizing to Thumbnail and support for "xxs"/"xs" sizes (520a642)
  • allow "updateComplete" to resolve to a boolean like the LitElement default (6127946)
  • allow Picker to be reparented (39e7309)
  • analyze errors, properly this time (df685a2)
  • analyze type errors, and add deprecated syntax tests (b7e67a1)
  • bad merge conflict resolution (e408d61)
  • correct custom property hoisting (a1d98dc)
  • correct max size calculation for overlays (0585f7f)
  • ensure Action Menu Item with [href] close the menu (6b3d87f)
  • ensure correct Menu Items are "selected" when passed into the overlay (46a25db)
  • ensure focus is managed when tabbing out of a menu (9bfa81d)
  • expand sync offering for elements with overlay content (0195843)
  • give Picker a focus helper to enable tab navigation in Safari (e796525)
  • hopefully fix CI (ea87245)
  • include late added items in the item list for the Picker (9232eb1)
  • issues with optionsMenu & menuItems (01a7e35)
  • menu: add support for submenu interactions (68399af)
  • menu: clarify menu internal focus management via preventScroll option (9ae092c)
  • menu: ensure active descendant is in view when activated (6edc351)
  • menu: only scrollIntoView when keyboard navigating (f4e9278)
  • overlay: move "escape" listener to "keydown" (813b341)
  • picker: accept new "value" and new option post first render (8f8c93f)
  • picker: add "quick select" action to right/left arrow keys (21895ee)
  • picker: allow menu items to be added, updated, and removed (73511ba)
  • picker: ensure focus visibility application (2679081)
  • picker: ensure that width is customizable from the outside (702b052)
  • picker: make "change" event bubbling and composed (1fdd33d)
  • picker: query less strictly to support automatically selecting values (969f966)
  • picker: use "modal" as the menu overlay interaction (c8fbbe2)
  • prevent console.log in source and test files (3ee082c)
  • remove usage where deprecated (387db3b)
  • simplify focus application in Menu (6140169)
  • simplify optionsMenu usage and fix tests (91241b7)
  • slot documentation (0ebd260)
  • split-button tests & lots of cleanup based on review feedback (10b4a04), closes #1189
  • style icons in Picker correctly (0bbdf84)
  • support a wider number of sizes (ee44978)
  • update Picker label via MutationObserver instead of "slotchange" (196998e)
  • update screen reader interface with menu items list (16756b5)
  • update to latest spectrum-css packages (a5ca19f)

Features #

  • add selects attribute to menu (bdf2578)
  • add t-shirt sizing with visual regressions to checkbox and picker elements (ce47ec8)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • conditionally load focus-visible polyfill (6b5e5cf)
  • delivery dev mode messages in various packages (62370a1)
  • deprecate sp-menu in PickerBase derived classes (bbb773c)
  • include all Dev Mode files in side effects (f70817c)
  • picker: process field-label content for more accurate a11y tree (dc9df54)
  • picker: replace dropdown with picker component (30b8bc7)
  • picker: support responsive delivery of menu (20031d1)
  • picker: update "icons-only" to "icons=only" to support more variations (de16a62)
  • picker: use new tokens (7d65b69)
  • reparentChildren - refactored arguments - breaking change (dea2bc5)
  • sets action-menu quiet to false by default, fixes #3040 (8414cab)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • tabs: add sp-tab-panel element (b17d276)
  • update lit-* dependencies, wip (377f3c8)
  • use latest exports specification (a7ecf4b)

Performance Improvements #

  • reorganize inheritance and composition in Menu Items (d96ccb6)

0.15.2 (2023-04-24) #

Note: Version bump only for package @spectrum-web-components/picker

0.15.1 (2023-04-05) #

Note: Version bump only for package @spectrum-web-components/picker

0.15.0 (2023-03-22) #

Features #

  • sets action-menu quiet to false by default, fixes #3040 (8414cab)

0.14.2 (2023-03-08) #

Note: Version bump only for package @spectrum-web-components/picker

0.14.1 (2023-02-13) #

Note: Version bump only for package @spectrum-web-components/picker

0.14.0 (2023-02-08) #

Features #

  • picker: use new tokens (7d65b69)

0.13.11 (2023-01-23) #

Note: Version bump only for package @spectrum-web-components/picker

0.13.10 (2023-01-09) #

Note: Version bump only for package @spectrum-web-components/picker

0.13.9 (2022-12-08) #

Note: Version bump only for package @spectrum-web-components/picker

0.13.8 (2022-11-21) #

Note: Version bump only for package @spectrum-web-components/picker

0.13.7 (2022-11-14) #

Note: Version bump only for package @spectrum-web-components/picker

0.13.6 (2022-10-28) #

Bug Fixes #

  • ensure Action Menu Item with [href] close the menu (6b3d87f)

0.13.5 (2022-10-17) #

Bug Fixes #

  • style icons in Picker correctly (0bbdf84)

0.13.4 (2022-10-10) #

Note: Version bump only for package @spectrum-web-components/picker

0.13.3 (2022-09-15) #

Bug Fixes #

  • action-menu: fix 2510, unable to control top-level action-menu selection (c9198c2)
  • action-menu: never set item selected values when selects is undefined (5237fdb)

0.13.2 (2022-09-14) #

Bug Fixes #

  • overlay: move "escape" listener to "keydown" (813b341)

0.13.1 (2022-08-24) #

Note: Version bump only for package @spectrum-web-components/picker

0.13.0 (2022-08-09) #

Features #

  • include all Dev Mode files in side effects (f70817c)

0.12.0 (2022-08-04) #

Bug Fixes #

  • action-menu: stop stripping selected state from submenu items (968d1f2)
  • picker: query less strictly to support automatically selecting values (969f966)

Features #

  • delivery dev mode messages in various packages (62370a1)

0.11.5 (2022-07-18) #

Note: Version bump only for package @spectrum-web-components/picker

0.11.4 (2022-06-29) #

Bug Fixes #

  • update Picker label via MutationObserver instead of "slotchange" (196998e)

0.11.3 (2022-06-07) #

Note: Version bump only for package @spectrum-web-components/picker

0.11.2 (2022-05-27) #

Note: Version bump only for package @spectrum-web-components/picker

0.11.1 (2022-05-12) #

Note: Version bump only for package @spectrum-web-components/picker

0.11.0 (2022-04-21) #

Bug Fixes #

  • allow Picker to be reparented (39e7309)
  • correct custom property hoisting (a1d98dc)
  • ensure correct Menu Items are "selected" when passed into the overlay (46a25db)

Features #

  • conditionally load focus-visible polyfill (6b5e5cf)
  • reparentChildren - refactored arguments - breaking change (dea2bc5)

0.10.6 (2022-03-30) #

Note: Version bump only for package @spectrum-web-components/picker

0.10.5 (2022-03-08) #

Note: Version bump only for package @spectrum-web-components/picker

0.10.4 (2022-03-08) #

Note: Version bump only for package @spectrum-web-components/picker

0.10.3 (2022-03-04) #

Bug Fixes #

  • menu: add support for submenu interactions (68399af)

0.10.2 (2022-02-22) #

Note: Version bump only for package @spectrum-web-components/picker

0.10.1 (2022-02-03) #

Note: Version bump only for package @spectrum-web-components/picker

0.10.0 (2022-02-02) #

Features #

  • picker: support responsive delivery of menu (20031d1)

0.9.4 (2022-01-26) #

Note: Version bump only for package @spectrum-web-components/picker

0.9.3 (2022-01-26) #

Bug Fixes #

  • picker: make "change" event bubbling and composed (1fdd33d)

0.9.2 (2022-01-07) #

Note: Version bump only for package @spectrum-web-components/picker

0.9.1 (2021-12-13) #

Bug Fixes #

  • add t-shirt sizing to Thumbnail and support for "xxs"/"xs" sizes (520a642)
  • picker: allow menu items to be added, updated, and removed (73511ba)

0.9.0 (2021-11-08) #

Features #

  • update lit-* dependencies, wip (377f3c8)

0.8.1 (2021-11-08) #

Bug Fixes #

  • abstract "hasVisibleFocusInTree" functionality and return trigger focus after close (4f39f2c)

0.8.0 (2021-11-02) #

Bug Fixes #

  • update screen reader interface with menu items list (16756b5)
  • picker: use "modal" as the menu overlay interaction (c8fbbe2)
  • include late added items in the item list for the Picker (9232eb1)

Features #

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.7.5 (2021-10-12) #

Note: Version bump only for package @spectrum-web-components/picker

0.7.4 (2021-10-05) #

Note: Version bump only for package @spectrum-web-components/picker

0.7.3 (2021-09-20) #

Note: Version bump only for package @spectrum-web-components/picker

0.7.2 (2021-09-13) #

Bug Fixes #

  • give Picker a focus helper to enable tab navigation in Safari (e796525)
  • simplify focus application in Menu (6140169)

0.7.1 (2021-08-24) #

Note: Version bump only for package @spectrum-web-components/picker

0.7.0 (2021-08-17) #

Features #

  • picker: update "icons-only" to "icons=only" to support more variations (de16a62)

Performance Improvements #

  • reorganize inheritance and composition in Menu Items (d96ccb6)

0.6.0 (2021-08-03) #

Bug Fixes #

  • allow "updateComplete" to resolve to a boolean like the LitElement default (6127946)
  • expand sync offering for elements with overlay content (0195843)

Features #

  • add selects attribute to menu (bdf2578)

0.5.4 (2021-07-22) #

Note: Version bump only for package @spectrum-web-components/picker

0.5.3 (2021-07-01) #

Bug Fixes #

  • add icon present and icon-only support to Picker (f6887a3)

0.5.2 (2021-06-16) #

Bug Fixes #

  • prevent console.log in source and test files (3ee082c)

0.5.1 (2021-06-07) #

Bug Fixes #

  • menu: clarify menu internal focus management via preventScroll option (9ae092c)
  • ensure focus is managed when tabbing out of a menu (9bfa81d)

0.5.0 (2021-05-24) #

Features #

  • tabs: add sp-tab-panel element (b17d276)

0.4.5 (2021-05-12) #

Bug Fixes #

  • picker: ensure focus visibility application (2679081)

0.4.4 (2021-04-15) #

Bug Fixes #

  • menu: only scrollIntoView when keyboard navigating (f4e9278)

0.4.3 (2021-04-09) #

Bug Fixes #

  • picker: accept new "value" and new option post first render (8f8c93f)

0.4.2 (2021-03-29) #

Bug Fixes #

  • correct max size calculation for overlays (0585f7f)

0.4.1 (2021-03-22) #

Note: Version bump only for package @spectrum-web-components/picker

0.4.0 (2021-03-22) #

Bug Fixes #

  • add support for "readonly" attribute (4bce3b7)
  • analyze errors, properly this time (df685a2)
  • analyze type errors, and add deprecated syntax tests (b7e67a1)
  • bad merge conflict resolution (e408d61)
  • hopefully fix CI (ea87245)
  • issues with optionsMenu & menuItems (01a7e35)
  • remove usage where deprecated (387db3b)
  • simplify optionsMenu usage and fix tests (91241b7)
  • slot documentation (0ebd260)
  • split-button tests & lots of cleanup based on review feedback (10b4a04), closes #1189

Features #

  • picker: process field-label content for more accurate a11y tree (dc9df54)
  • deprecate sp-menu in PickerBase derived classes (bbb773c)

0.3.1 (2021-03-05) #

Note: Version bump only for package @spectrum-web-components/picker

0.3.0 (2021-03-04) #

Bug Fixes #

  • menu: ensure active descendant is in view when activated (6edc351)
  • picker: add "quick select" action to right/left arrow keys (21895ee)
  • picker: ensure that width is customizable from the outside (702b052)
  • support a wider number of sizes (ee44978)

Features #

  • use latest exports specification (a7ecf4b)

0.2.0 (2021-02-11) #

Bug Fixes #

  • update to latest spectrum-css packages (a5ca19f)

Features #

  • add t-shirt sizing with visual regressions to checkbox and picker elements (ce47ec8)

0.1.0 (2021-02-02) #

Features #

  • picker: replace dropdown with picker component (30b8bc7)

Attributes and Properties #

Property Attribute Type Default Description disabled disabled boolean false Disable this control. It will not receive focus or events focused focused boolean false forcePopover force-popover boolean false Forces the Picker to render as a popover on mobile instead of a tray. icons icons 'only' | 'none' | undefined invalid invalid boolean false label label string | undefined open open boolean false pending pending boolean false Whether the items are currently loading. pendingLabel pending-label string 'Pending' Defines a string value that labels the Picker while it is in pending state. placement placement "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" 'bottom-start' quiet quiet boolean false readonly readonly boolean false tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property value value string ''

Slots #

Name Description description The description content for the Picker label The placeholder content for the Picker tooltip Tooltip to to be applied to the the Picker Button default slot menu items to be listed in the Picker

Events #

Name Type Description change Event Announces that the `value` of the element has changed scroll Event sp-closed Event Announces that the overlay has been closed sp-opened Event Announces that the overlay has been opened

Description #

An <sp-picker> is an alternative to HTML's <select> element. Use <sp-menu-item> elements to outline the options that will be made available to the user when interacting with the <sp-picker> element.

Usage #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/picker

Import the side effectful registration of <sp-picker> via:

import '@spectrum-web-components/picker/sp-picker.js';

The default of <sp-picker> will load dependencies in @spectrum-web-components/overlay asynchronously via a dynamic import. In the case that you would like to import those tranverse dependencies statically, import the side effectful registration of <sp-picker> as follows:

import '@spectrum-web-components/picker/sync/sp-picker.js';

When looking to leverage the Picker base class as a type and/or for extension purposes, do so via:

import { Picker } from '@spectrum-web-components/picker';

Sizes #

Small 
<sp-field-group>
    <div>
        <sp-field-label for="picker-s" size="s">Selection type:</sp-field-label>
        <sp-picker id="picker-s" size="s" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
    <div>
        <sp-field-label for="picker-s-quiet" size="s">
            Selection type:
        </sp-field-label>
        <sp-picker id="picker-s-quiet" quiet size="s" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
</sp-field-group>
 Medium 
<sp-field-group>
    <div>
        <sp-field-label for="picker-m" size="m">Selection type:</sp-field-label>
        <sp-picker id="picker-m" size="m" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
    <div>
        <sp-field-label for="picker-m-quiet" size="m">
            Selection type:
        </sp-field-label>
        <sp-picker id="picker-m-quiet" quiet size="m" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
</sp-field-group>
 Large 
<sp-field-group>
    <div>
        <sp-field-label for="picker-l" size="l">Selection type:</sp-field-label>
        <sp-picker id="picker-l" size="l" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
    <div>
        <sp-field-label for="picker-l-quiet" size="l">
            Selection type:
        </sp-field-label>
        <sp-picker id="picker-l-quiet" quiet size="l" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
</sp-field-group>
 Extra Large 
<sp-field-group>
    <div>
        <sp-field-label for="picker-xl" size="xl">
            Selection type:
        </sp-field-label>
        <sp-picker id="picker-xl" size="xl" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
    <div>
        <sp-field-label for="picker-xl-quiet" size="xl">
            Selection type:
        </sp-field-label>
        <sp-picker id="picker-xl-quiet" quiet size="xl" label="Selection type">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save selection</sp-menu-item>
            <sp-menu-item disabled>Make work path</sp-menu-item>
        </sp-picker>
    </div>
</sp-field-group>

Icons #

<sp-menu-item>s in an <sp-picker> that are provided content addressed to their icon slot will be passed to the <sp-picker> element when that item is chosen.

<sp-field-label for="picker-icons">Choose an action...</sp-field-label>
<sp-picker label="What would you like to do?" value="item-2" id="picker-icons">
    <sp-menu-item>
        <sp-icon-save-floppy slot="icon"></sp-icon-save-floppy>
        Save
    </sp-menu-item>
    <sp-menu-item>
        <sp-icon-stopwatch slot="icon"></sp-icon-stopwatch>
        Finish
    </sp-menu-item>
    <sp-menu-item>
        <sp-icon-user-activity slot="icon"></sp-icon-user-activity>
        Review
    </sp-menu-item>
</sp-picker>

When you choose to leverage <sp-menu-item> elements without text content, you will need to be sure to leverage the value attribute so that the <sp-picker> element can differentiate between the available options. Further, it is important that you apply accessible labeling to the [slot="icon"] content as follows:

<sp-field-label for="picker-icons-only">Choose an action...</sp-field-label>
<sp-picker
    label="What would you like to do?"
    value="item-2"
    id="picker-icons-only"
>
    <sp-menu-item value="item-1">
        <sp-icon-save-floppy slot="icon" label="Save"></sp-icon-save-floppy>
    </sp-menu-item>
    <sp-menu-item value="item-2">
        <sp-icon-stopwatch slot="icon" label="Finish"></sp-icon-stopwatch>
    </sp-menu-item>
    <sp-menu-item value="item-3">
        <sp-icon-user-activity
            slot="icon"
            label="Review"
        ></sp-icon-user-activity>
    </sp-menu-item>
</sp-picker>

Advanced icon management #

The icons attribute allows you to manage whether to only display the icon in the <sp-picker> element or to display none of the icons in the <sp-picker>.

When using icons="only" and your <sp-menu-item> elements still have text content, that content will be applied to <sp-picker> element in a non-visible way.

<sp-field-label for="picker-icons-value">Choose an action...</sp-field-label>
<sp-picker
    label="What would you like to do?"
    value="item-2"
    id="picker-icons-value"
    icons="only"
>
    <sp-menu-item>
        <sp-icon-save-floppy slot="icon"></sp-icon-save-floppy>
        Save
    </sp-menu-item>
    <sp-menu-item>
        <sp-icon-stopwatch slot="icon"></sp-icon-stopwatch>
        Finish
    </sp-menu-item>
    <sp-menu-item>
        <sp-icon-user-activity slot="icon"></sp-icon-user-activity>
        Review
    </sp-menu-item>
</sp-picker>

When using icons="none", the icons will only be available in the overlaid menu.

<sp-field-label for="picker-icons-none">Choose an action...</sp-field-label>
<sp-picker
    label="What would you like to do?"
    value="item-2"
    id="picker-icons-none"
    icons="none"
>
    <sp-menu-item>
        <sp-icon-save-floppy slot="icon"></sp-icon-save-floppy>
        Save
    </sp-menu-item>
    <sp-menu-item>
        <sp-icon-stopwatch slot="icon"></sp-icon-stopwatch>
        Finish
    </sp-menu-item>
    <sp-menu-item>
        <sp-icon-user-activity slot="icon"></sp-icon-user-activity>
        Review
    </sp-menu-item>
</sp-picker>

Value #

When the value of an <sp-picker> matches the value attribute or the trimmed textContent (or itemText) of a descendent <sp-menu-item> element, it will make that element as selected.

Matching value #

<sp-field-label for="picker-value">Selection type:</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    value="item-2"
    id="picker-value"
>
    <sp-menu-item value="item-1">Deselect</sp-menu-item>
    <sp-menu-item value="item-2">Select inverse</sp-menu-item>
    <sp-menu-item value="item-3">Feather...</sp-menu-item>
    <sp-menu-item value="item-4">Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item value="item-5">Save selection</sp-menu-item>
    <sp-menu-item disabled value="item-6">Make work path</sp-menu-item>
</sp-picker>

Matching itemText #

<sp-field-label for="picker-item-text">Selection type:</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    value="Feather..."
    id="picker-item-text"
>
    <sp-menu-item>Deselect</sp-menu-item>
    <sp-menu-item>Select inverse</sp-menu-item>
    <sp-menu-item>Feather...</sp-menu-item>
    <sp-menu-item>Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item>Save selection</sp-menu-item>
    <sp-menu-item>Make work path</sp-menu-item>
</sp-picker>

States #

Invalid #

<sp-field-label for="picker-invalid">Standard:</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    invalid
    id="picker-invalid"
>
    <sp-menu-item>Deselect</sp-menu-item>
    <sp-menu-item>Select inverse</sp-menu-item>
    <sp-menu-item>Feather...</sp-menu-item>
    <sp-menu-item>Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item>Save selection</sp-menu-item>
    <sp-menu-item disabled>Make work path</sp-menu-item>
</sp-picker>
<br />
<br />
<sp-field-label for="picker-invalid-quiet">Quiet:</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    invalid
    quiet
    id="picker-invalid-quiet"
>
    <sp-menu-item>Deselect</sp-menu-item>
    <sp-menu-item>Select inverse</sp-menu-item>
    <sp-menu-item>Feather...</sp-menu-item>
    <sp-menu-item>Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item>Save selection</sp-menu-item>
    <sp-menu-item disabled>Make work path</sp-menu-item>
</sp-picker>

Side Label #

<sp-field-label side-aligned="start" for="picker-sideLabel">
    Standard:
</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    id="picker-sideLabel"
>
    <sp-menu-item>Deselect</sp-menu-item>
    <sp-menu-item>Select inverse</sp-menu-item>
    <sp-menu-item>Feather...</sp-menu-item>
    <sp-menu-item>Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item>Save selection</sp-menu-item>
    <sp-menu-item disabled>Make work path</sp-menu-item>
</sp-picker>
<br />
<br />
<sp-field-label side-aligned="start" for="picker-sideLabel-quiet">
    Quiet:
</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    quiet
    id="picker-sideLabel-quiet"
>
    <sp-menu-item>Deselect</sp-menu-item>
    <sp-menu-item>Select inverse</sp-menu-item>
    <sp-menu-item>Feather...</sp-menu-item>
    <sp-menu-item>Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item>Save selection</sp-menu-item>
    <sp-menu-item disabled>Make work path</sp-menu-item>
</sp-picker>

Disabled #

<sp-field-label for="picker-disabled">Standard:</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    disabled
    id="picker-disabled"
>
    <sp-menu-item>Deselect</sp-menu-item>
    <sp-menu-item>Select inverse</sp-menu-item>
    <sp-menu-item>Feather...</sp-menu-item>
    <sp-menu-item>Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item>Save selection</sp-menu-item>
    <sp-menu-item disabled>Make work path</sp-menu-item>
</sp-picker>
<br />
<br />
<sp-field-label for="picker-disabled-quiet">Quiet:</sp-field-label>
<sp-picker
    label="Select a Country with a very long label, too long in fact"
    disabled
    quiet
    id="picker-disabled-quiet"
>
    <sp-menu-item>Deselect</sp-menu-item>
    <sp-menu-item>Select inverse</sp-menu-item>
    <sp-menu-item>Feather...</sp-menu-item>
    <sp-menu-item>Select and mask...</sp-menu-item>
    <sp-menu-divider></sp-menu-divider>
    <sp-menu-item>Save selection</sp-menu-item>
    <sp-menu-item disabled>Make work path</sp-menu-item>
</sp-picker>

Pending #

When in pending state, <sp-picker> elements will not respond to click events and will be delivered with a <sp-progress-circle> to visually outline that it is pending. It will not toggle open or display its <sp-menu-item> descendants until the attribute is removed.

<sp-field-label for="picker-loading">Standard:</sp-field-label>
<sp-picker id="picker-loading" label="Loading blending modes..." pending>
    <sp-menu-item>Pass through</sp-menu-item>
    <sp-menu-item>Normal</sp-menu-item>
    <sp-menu-item>Multiply</sp-menu-item>
    <sp-menu-item>Screen</sp-menu-item>
</sp-picker>
<br />
<br />
<sp-field-label for="picker-loading-quiet">Quiet:</sp-field-label>
<sp-picker
    id="picker-loading-quiet"
    label="Loading blending modes..."
    pending
    quiet
>
    <sp-menu-item>Pass through</sp-menu-item>
    <sp-menu-item>Normal</sp-menu-item>
    <sp-menu-item>Multiply</sp-menu-item>
    <sp-menu-item>Screen</sp-menu-item>
</sp-picker>

Force Popover on Mobile Devices #

On mobile, the menu can be exposed in either a sp-popover or sp-tray. By default, sp-picker will render an sp-tray. If you would like to render sp-popover on mobile, add the attribute forcePopover to the sp-picker.

Usage Guidance:

  • Use a tray when a menu’s proximity to its trigger is considered to be less important to the experience, or for showing a volume of content that is too overwhelming for a popover.
  • Use a popover when a menu’s proximity to its trigger is considered to be important to the experience, or for showing a volume of content that is manageable for a popover.

To see this functionality in action, load this page from your mobile device or use Chrome DevTools (or equivalent) and select a mobile device once the Device Toolbar (the phone/tablet icon) is active.

<sp-field-label for="picker-tray">
    Do you want to see a tray menu?
</sp-field-label>
<sp-picker id="picker-tray" label="Select an option">
    <sp-menu-item value="option-1">Yes</sp-menu-item>
    <sp-menu-item value="option-2">No</sp-menu-item>
</sp-picker>
<br />
<sp-field-label for="picker-popover">
    Do you want to see a popover menu?
</sp-field-label>
<sp-picker id="picker-popover" label="Select an option" forcePopover>
    <sp-menu-item value="option-1">Yes</sp-menu-item>
    <sp-menu-item value="option-2">No</sp-menu-item>
</sp-picker>

Accessibility #

To render accessibly, an <sp-picker> element should be paired with an <sp-field-label> element that has a for attribute referencing the id of the <sp-picker> element. For an accessible label that renders within the bounds of the picker itself, but still fulfills the accessibility contract, use the label attribute or a <span slot="label"> as a child element of <sp-picker>.