@spectrum-web-components/picker-button

Description

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-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';

Sizes

Small

<sp-picker-button size="s"></sp-picker-button>
<br />
<sp-picker-button size="s"><span slot="label">All</span></sp-picker-button>

Medium

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

Large

<sp-picker-button size="l"></sp-picker-button>
<br />
<sp-picker-button size="l"><span slot="label">All</span></sp-picker-button>

Extra Large

<sp-picker-button size="xl"></sp-picker-button>
<br />
<sp-picker-button size="xl"><span slot="label">All</span></sp-picker-button>

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>

Modifying attributes

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>

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>

Changelog

1.0.1 (2024-11-11)

Bug Fixes

• action-group: add null check for slotElement in manageButtons (#4924) (60db5ab)
• icon: remove size300 suffix from chevron and checkmark icons in Spectrum 2 (#4904) (a22f42b)
• menu: prevent sp-menu-item text-align cascading (#4868) (6663820)
• number-field, slider: ensure cached value is cleared when toggling between different steps (#4846) (1c84c96)
• number-field: allow only numeric characters for Japanese/Chinese IME (#4817) (a791bd1)
• overlay: ensure smooth animation when opening modal overlays (#4879) (cd8dad7)
• overlay: overlay closing another overlay (#4880) (30434fa)
• overlay: remove flex display for dialog (#4902) (48448ea)
• picker: don't handle pointerdown for touch devices (#4850) (3a62d13)
• search: clear button ui in express (#4910) (f88e1e2)
• slider: allow handler to be focusable when slider is editable (23f8b89)
• slider: update slider config to process the tick css correctly (#4905) (7b1dfd0)

Reverts

• Revert "fix(slider): allow handler to be focusable when slider is editable" (#4907) (92850ad), closes #4907