sp-picker

Examples API

Attributes and Properties #

Property Attribute Type Default Description
autofocus autofocus boolean false When this control is rendered, focus it automatically
dir dir 'ltr' | 'rtl' 'ltr'
disabled disabled boolean false Disable this control. It will not receive focus or events
focused focused boolean false
icons icons 'only' | 'none' | undefined
invalid invalid boolean false
label label string | undefined
open open boolean false
placement placement "auto" | "auto-start" | "auto-end" | "top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "none" 'bottom-start'
quiet quiet boolean false
readonly readonly boolean false
size size ElementSize
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
label The placeholder content for the Picker
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
sp-closed Event Announces that the overlay has been closed
sp-opened Event Announces that the overlay has been opened

CSS Custom Properties #

Name Default
--spectrum-alias-body-text-font-family var(--spectrum-global-font-family-base)
--spectrum-alias-component-text-line-height var(--spectrum-global-font-line-height-small)
--spectrum-picker-l-texticon-border-radius var(--spectrum-alias-component-border-radius)
--spectrum-picker-l-texticon-border-size var(--spectrum-alias-border-size-thin)
--spectrum-picker-l-texticon-error-icon-margin-left var(--spectrum-global-dimension-size-185)
--spectrum-picker-l-texticon-height var(--spectrum-global-dimension-size-500)
--spectrum-picker-l-texticon-icon-gap var(--spectrum-global-dimension-size-115)
--spectrum-picker-l-texticon-min-width var(--spectrum-global-dimension-size-750)
--spectrum-picker-l-texticon-placeholder-font-style var(--spectrum-global-font-style-italic)
--spectrum-picker-l-texticon-placeholder-font-weight var(--spectrum-global-font-weight-regular)
--spectrum-picker-l-texticon-popover-max-width var(--spectrum-global-dimension-size-3000)
--spectrum-picker-l-texticon-text-size var(--spectrum-global-dimension-font-size-200)
--spectrum-picker-l-texticon-ui-icon-gap var(--spectrum-global-dimension-size-115)
--spectrum-picker-l-texticon-width var(--spectrum-global-dimension-size-2500)
--spectrum-picker-l-textonly-padding-left var(--spectrum-global-dimension-size-185)
--spectrum-picker-l-textonly-padding-right var(--spectrum-global-dimension-size-185)
--spectrum-picker-m-quiet-texticon-background-color var(--spectrum-alias-component-background-color-quiet-default)
--spectrum-picker-m-quiet-texticon-background-color-disabled var(--spectrum-alias-component-background-color-quiet-disabled)
--spectrum-picker-m-quiet-texticon-background-color-down var(--spectrum-alias-background-color-transparent)
--spectrum-picker-m-quiet-texticon-background-color-hover var(--spectrum-alias-component-background-color-quiet-hover)
--spectrum-picker-m-quiet-texticon-background-color-key-focus var(--spectrum-alias-component-background-color-quiet-key-focus)
--spectrum-picker-m-quiet-texticon-border-color var(--spectrum-alias-component-border-color-quiet-default)
--spectrum-picker-m-quiet-texticon-border-color-down var(--spectrum-alias-component-border-color-quiet-down)
--spectrum-picker-m-quiet-texticon-placeholder-text-color-key-focus var(--spectrum-alias-placeholder-text-color-hover)
--spectrum-picker-m-quiet-texticon-popover-offset-x var(--spectrum-global-dimension-size-150)
--spectrum-picker-m-texticon-background-color var(--spectrum-alias-component-background-color-default)
--spectrum-picker-m-texticon-background-color-disabled var(--spectrum-alias-component-background-color-disabled)
--spectrum-picker-m-texticon-background-color-down var(--spectrum-alias-component-background-color-down)
--spectrum-picker-m-texticon-background-color-hover var(--spectrum-alias-component-background-color-hover)
--spectrum-picker-m-texticon-background-color-key-focus var(--spectrum-alias-component-background-color-key-focus)
--spectrum-picker-m-texticon-border-color var(--spectrum-alias-component-border-color-default)
--spectrum-picker-m-texticon-border-color-down var(--spectrum-alias-component-border-color-down)
--spectrum-picker-m-texticon-border-color-error var(--spectrum-semantic-negative-color-default)
--spectrum-picker-m-texticon-border-color-error-down var(--spectrum-semantic-negative-color-down)
--spectrum-picker-m-texticon-border-color-error-hover var(--spectrum-semantic-negative-color-hover)
--spectrum-picker-m-texticon-border-color-error-key-focus var(--spectrum-alias-border-color-key-focus)
--spectrum-picker-m-texticon-border-color-hover var(--spectrum-alias-component-border-color-hover)
--spectrum-picker-m-texticon-border-color-key-focus var(--spectrum-alias-component-border-color-key-focus)
--spectrum-picker-m-texticon-border-radius var(--spectrum-alias-component-border-radius)
--spectrum-picker-m-texticon-border-size var(--spectrum-alias-border-size-thin)
--spectrum-picker-m-texticon-error-icon-margin-left var(--spectrum-global-dimension-size-150)
--spectrum-picker-m-texticon-height var(--spectrum-global-dimension-size-400)
--spectrum-picker-m-texticon-icon-color var(--spectrum-alias-component-icon-color-default)
--spectrum-picker-m-texticon-icon-color-disabled var(--spectrum-alias-component-icon-color-disabled)
--spectrum-picker-m-texticon-icon-color-hover var(--spectrum-alias-component-icon-color-hover)
--spectrum-picker-m-texticon-icon-color-key-focus var(--spectrum-alias-component-icon-color-key-focus)
--spectrum-picker-m-texticon-icon-gap var(--spectrum-global-dimension-size-100)
--spectrum-picker-m-texticon-min-width var(--spectrum-global-dimension-size-600)
--spectrum-picker-m-texticon-placeholder-font-style var(--spectrum-global-font-style-italic)
--spectrum-picker-m-texticon-placeholder-font-weight var(--spectrum-global-font-weight-regular)
--spectrum-picker-m-texticon-placeholder-text-color var(--spectrum-alias-placeholder-text-color)
--spectrum-picker-m-texticon-placeholder-text-color-disabled var(--spectrum-alias-text-color-disabled)
--spectrum-picker-m-texticon-placeholder-text-color-down var(--spectrum-alias-placeholder-text-color-down)
--spectrum-picker-m-texticon-placeholder-text-color-hover var(--spectrum-alias-placeholder-text-color-hover)
--spectrum-picker-m-texticon-placeholder-text-color-key-focus var(--spectrum-alias-placeholder-text-color-hover)
--spectrum-picker-m-texticon-placeholder-text-color-mouse-focus var(--spectrum-alias-placeholder-text-color-down)
--spectrum-picker-m-texticon-popover-max-width var(--spectrum-global-dimension-size-2400)
--spectrum-picker-m-texticon-text-color var(--spectrum-alias-component-text-color-default)
--spectrum-picker-m-texticon-text-color-disabled var(--spectrum-alias-component-text-color-disabled)
--spectrum-picker-m-texticon-text-color-hover var(--spectrum-alias-component-text-color-hover)
--spectrum-picker-m-texticon-text-color-key-focus var(--spectrum-alias-component-text-color-key-focus)
--spectrum-picker-m-texticon-text-size var(--spectrum-global-dimension-font-size-100)
--spectrum-picker-m-texticon-ui-icon-gap var(--spectrum-global-dimension-size-100)
--spectrum-picker-m-texticon-validation-icon-color-error var(--spectrum-semantic-negative-icon-color)
--spectrum-picker-m-texticon-width var(--spectrum-global-dimension-size-2400)
--spectrum-picker-m-textonly-padding-left var(--spectrum-global-dimension-size-150)
--spectrum-picker-m-textonly-padding-right var(--spectrum-global-dimension-size-150)
--spectrum-picker-s-texticon-border-radius var(--spectrum-alias-component-border-radius)
--spectrum-picker-s-texticon-border-size var(--spectrum-alias-border-size-thin)
--spectrum-picker-s-texticon-error-icon-margin-left var(--spectrum-global-dimension-size-100)
--spectrum-picker-s-texticon-height var(--spectrum-global-dimension-size-300)
--spectrum-picker-s-texticon-icon-gap var(--spectrum-global-dimension-size-85)
--spectrum-picker-s-texticon-min-width var(--spectrum-global-dimension-size-450)
--spectrum-picker-s-texticon-placeholder-font-style var(--spectrum-global-font-style-italic)
--spectrum-picker-s-texticon-placeholder-font-weight var(--spectrum-global-font-weight-regular)
--spectrum-picker-s-texticon-popover-max-width var(--spectrum-global-dimension-size-1800)
--spectrum-picker-s-texticon-text-size var(--spectrum-global-dimension-font-size-75)
--spectrum-picker-s-texticon-ui-icon-gap var(--spectrum-global-dimension-size-85)
--spectrum-picker-s-texticon-width var(--spectrum-global-dimension-size-2000)
--spectrum-picker-s-textonly-padding-left var(--spectrum-global-dimension-size-115)
--spectrum-picker-s-textonly-padding-right var(--spectrum-global-dimension-size-115)
--spectrum-picker-xl-texticon-border-radius var(--spectrum-alias-component-border-radius)
--spectrum-picker-xl-texticon-border-size var(--spectrum-alias-border-size-thin)
--spectrum-picker-xl-texticon-error-icon-margin-left var(--spectrum-global-dimension-size-225)
--spectrum-picker-xl-texticon-height var(--spectrum-global-dimension-size-600)
--spectrum-picker-xl-texticon-icon-gap var(--spectrum-global-dimension-size-125)
--spectrum-picker-xl-texticon-min-width var(--spectrum-global-dimension-size-900)
--spectrum-picker-xl-texticon-placeholder-font-style var(--spectrum-global-font-style-italic)
--spectrum-picker-xl-texticon-placeholder-font-weight var(--spectrum-global-font-weight-regular)
--spectrum-picker-xl-texticon-popover-max-width var(--spectrum-global-dimension-size-3600)
--spectrum-picker-xl-texticon-text-size var(--spectrum-global-dimension-font-size-300)
--spectrum-picker-xl-texticon-ui-icon-gap var(--spectrum-global-dimension-size-125)
--spectrum-picker-xl-texticon-width var(--spectrum-global-dimension-size-3000)
--spectrum-picker-xl-textonly-padding-left var(--spectrum-global-dimension-size-225)
--spectrum-picker-xl-textonly-padding-right var(--spectrum-global-dimension-size-225)
--spectrum-popover-border-size var(--spectrum-alias-border-size-thin)

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>

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:</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>

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.