sp-picker
NPM
0.48.1
Storybook
View Storybook
Try it on
webcomponents.dev
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 #
disabled
disabled
boolean
false
focused
focused
boolean
false
icons
icons
'only' | 'none' | undefined
invalid
invalid
boolean
false
label
label
string | undefined
open
open
boolean
false
pending
pending
boolean
false
pendingLabel
pending-label
string
'Pending'
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
value
value
string
''
Slots #
description
label
tooltip
default slot
Events #
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 #
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 #
<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>
<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>
<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>
<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>
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>
.