sp-picker-button

NPM 1.4.0

View Storybook
Overview API Changelog

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

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/picker-button

Import 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

Small Medium 
<sp-picker-button size="m"></sp-picker-button>
<br />
<sp-picker-button size="m"><span slot="label">All</span></sp-picker-button>
 Large Extra Large

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 label slot.
  • Use aria-label attribute.
  • Set the aria-labelledby attribute 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-controls property to the ID reference of the menu element.
  • Set the aria-haspopup property to "menu" or "true".
  • Set the aria-expanded property 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 Enter or Space is pressed.
  • Optional: Open the menu and focus on first menu item when Down Arrow is pressed.
  • Optional: Open the menu and focus on last menu item when Up Arrow is pressed.