adobe
Overview
An <sp-picker-button> is used as a sub-component of patterns like the <sp-combobox> (release pending) to pair a button interface with a text input. With its many custom states and alterations, it isn't likely to be leveraged directly outside of more complex UIs.
Usage
yarn add @spectrum-web-components/picker-buttonImport the side effectful registration of <sp-picker-button> via:
import '@spectrum-web-components/picker-button/sp-picker-button.js';When looking to leverage the PickerButton base class as a type and/or for extension purposes, do so via:
import { PickerButton } from '@spectrum-web-components/picker-button';Anatomy
Text and icon
With the use of the label slot, you can deliver an <sp-picker-button> with both an icon and a text label:
<sp-picker-button><span slot="label">All</span></sp-picker-button>Icon only
Without content addressed to the label slot, the <sp-picker-button> with both an icon and a text label:
<sp-picker-button></sp-picker-button>Custom icon
You can customize the icon in an <sp-picker-button> by addressing a new icon to the icon slot:
<sp-picker-button><sp-icon-add slot="icon"></sp-icon-add></sp-picker-button>Options
Sizes
<sp-tabs selected="m" auto label="Size Attribute Options"> <sp-tab value="s">Small</sp-tab> <sp-tab-panel value="s"><sp-picker-button size="s"></sp-picker-button>
<br />
<sp-picker-button size="s"><span slot="label">All</span></sp-picker-button><sp-picker-button size="m"></sp-picker-button>
<br />
<sp-picker-button size="m"><span slot="label">All</span></sp-picker-button><sp-picker-button size="l"></sp-picker-button>
<br />
<sp-picker-button size="l"><span slot="label">All</span></sp-picker-button><sp-picker-button size="xl"></sp-picker-button>
<br />
<sp-picker-button size="xl"><span slot="label">All</span></sp-picker-button>Rounded
When delivered as part of the express system, an <sp-picker-button> with the rounded attribute will be given deeply rounded corners:
<sp-picker-button rounded></sp-picker-button>
<br />
<sp-picker-button rounded><span slot="label">All</span></sp-picker-button>Quiet
When delivered with the quiet attribute, the <sp-picker-button> will take a less pronounced visual delivery:
<sp-picker-button quiet></sp-picker-button>
<br />
<sp-picker-button quiet><span slot="label">All</span></sp-picker-button>Position
By default the <sp-picker-button> will be given a position attribute with the value right, which is best leveraged at the right edge of an associated <sp-textfield> element. If your UI desires that the <sp-picker-button> be placed to the left of the related input, use the position attribute and set it to left:
<sp-picker-button position="left"></sp-picker-button>
<br />
<sp-picker-button position="left">
<span slot="label">All</span>
</sp-picker-button>States
Open
When paired with an expanded UI, e.g. an <sp-combobox> with its autocomplete options visible, an <sp-picker-button> should be given the open attribute to visual match the delivered state in the larger UI:
<sp-picker-button open></sp-picker-button>
<br />
<sp-picker-button open><span slot="label">All</span></sp-picker-button>Disabled
Leveraging the disabled attribute will dim the <sp-picker-button> and alter its presentation in the accessibility tree:
<sp-picker-button disabled></sp-picker-button>
<br />
<sp-picker-button disabled><span slot="label">All</span></sp-picker-button>Invalid
When delivered as part of the spectrum system, an <sp-picker-button> with the invalid attribute will be given a red border:
<sp-picker-button invalid></sp-picker-button>
<br />
<sp-picker-button invalid><span slot="label">All</span></sp-picker-button>Accessibility
The example below is for demonstration purposes. For an example implementation of <sp-picker-button> view Combobox.ts. For comprehensive information on menu button accessibility, see WAI ARIA Authoring Practice Guide's Menu Button Pattern.
<sp-field-label for="color">Color</sp-field-label>
<sp-textfield id="color"></sp-textfield>
<overlay-trigger type="modal">
<sp-picker-button
aria-controls="colors-menu"
aria-expanded="false"
aria-haspopup="menu"
aria-describedby="color"
slot="trigger"
></sp-picker-button>
<sp-tray slot="click-content">
<sp-menu id="colors-menu">
<sp-menu-item>Red</sp-menu-item>
<sp-menu-item>Blue</sp-menu-item>
</sp-menu>
</sp-tray>
</overlay-trigger>Include a label
To ensure menu items can be read by assistive technology, do one of the following:
- Place visible text in the component's
labelslot. - Use
aria-labelattribute. - Set the
aria-labelledbyattribute to the ID reference of the menu element.
Set aria properties correctly
To indicate to assistive technology what the button does, do all of the following:
- Set the
aria-controlsproperty to the ID reference of the menu element. - Set the
aria-haspopupproperty to"menu"or"true". - Set the
aria-expandedproperty to"menu"or"true"or"false"depending on whether the menu is displayed.
Add keyboard interaction
Ensure that picker button can be operated by keyboard users:
- Required: Open the menu and focus on first menu item when <kbd>Enter</kbd> or <kbd>Space</kbd> is pressed.
- Optional: Open the menu and focus on first menu item when <kbd>Down Arrow</kbd> is pressed.
- Optional: Open the menu and focus on last menu item when <kbd>Up Arrow</kbd> is pressed.