sp-picker-button

NPM 1.9.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 
<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>

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.

Attributes and Properties

Property Attribute Type Default Description active active boolean false disabled disabled boolean false Disable this control. It will not receive focus or events download download string | undefined Causes the browser to treat the linked URL as a download. href href string | undefined The URL that the hyperlink points to. label label string | undefined An accessible label that describes the component. It will be applied to aria-label, but not visually rendered. referrerpolicy referrerpolicy | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | undefined How much of the referrer to send when following the link. rel rel string | undefined The relationship of the linked URL as space-separated link types. tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property target target '_blank' | '_parent' | '_self' | '_top' | undefined Where to display the linked URL, as the name for a browsing context (a tab, window, or <iframe>). type type 'button' | 'submit' | 'reset' 'button' The default behavior of the button. Possible values are: `button` (default), `submit`, and `reset`.

Slots

Name Description default slot text content to be displayed in the Button element icon icon element(s) to display at the start of the button

Patch Changes

  • Updated dependencies [7d23140]:
    • @spectrum-web-components/button@1.9.0
    • @spectrum-web-components/icon@1.9.0
    • @spectrum-web-components/icons-ui@1.9.0
    • @spectrum-web-components/base@1.9.0
    • @spectrum-web-components/shared@1.9.0

1.8.0

Patch Changes

  • Updated dependencies [15be17d]:
    • @spectrum-web-components/button@1.8.0
    • @spectrum-web-components/icon@1.8.0
    • @spectrum-web-components/icons-ui@1.8.0
    • @spectrum-web-components/base@1.8.0
    • @spectrum-web-components/shared@1.8.0

1.7.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/button@1.7.0
    • @spectrum-web-components/icon@1.7.0
    • @spectrum-web-components/icons-ui@1.7.0
    • @spectrum-web-components/base@1.7.0
    • @spectrum-web-components/shared@1.7.0

1.6.0

Patch Changes

  • Updated dependencies [00eb0a8]:
    • @spectrum-web-components/button@1.6.0
    • @spectrum-web-components/icon@1.6.0
    • @spectrum-web-components/icons-ui@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • #5202 fa4be70 Thanks @Rajdeepc! - Updates the picker button component from version 6.0.0-s2-foundations.16 to 6.1.2. The update should bring the background colors for the picker button in line with S2-foundations design specs:

    default state: gray-50 to gray-100 hover state: gray-100 to gray-200 key-focus state: gray-100 to gray-200

  • Updated dependencies [4e06533]:

    • @spectrum-web-components/button@1.5.0
    • @spectrum-web-components/icon@1.5.0
    • @spectrum-web-components/icons-ui@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/button@1.4.0
    • @spectrum-web-components/icon@1.4.0
    • @spectrum-web-components/icons-ui@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/button@1.3.0
    • @spectrum-web-components/icon@1.3.0
    • @spectrum-web-components/icons-ui@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/picker-button

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/picker-button

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/picker-button

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/picker-button

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/picker-button

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/picker-button

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/picker-button

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/picker-button

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/picker-button

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/picker-button

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/picker-button

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/picker-button

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/picker-button

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/picker-button

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/picker-button

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/picker-button

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/picker-button

0.42.4 (2024-05-14)

Bug Fixes

  • picker-button: update quiet styles (#4383) (42bf291)

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/picker-button

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/picker-button

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/picker-button

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/picker-button

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/picker-button

0.41.0 (2024-02-13)

Features

  • icon: use core tokens (a11ef6b)

0.40.5 (2024-02-05)

Bug Fixes

  • combobox: add combobox pattern (#3894) (47d7d71), closes #3887

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/picker-button

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/picker-button

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/picker-button

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/picker-button

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/picker-button

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/picker-button

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/picker-button

0.39.2 (2023-10-13)

Bug Fixes

  • update deps graph, update link docs (#3709) (2deb284)

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/picker-button

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/picker-button

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/picker-button

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/picker-button

0.36.0 (2023-08-18)

Bug Fixes

  • picker-button: include missing dependency on @spectrum-web-components/button (#3515) (ed44c2b)

Features

  • picker-button: migrate to core tokens (b39219c)

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/picker-button

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/picker-button

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/picker-button

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/picker-button

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/picker-button

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/picker-button

0.30.0 (2023-05-03)

Features

  • add Picker Button pattern (31337b8)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)

0.1.11 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.10 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.9 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.8 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.7 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.6 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.5 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.4 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.3 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.2 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.1 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/picker-button

0.1.0 (2022-10-10)

Features

  • add Picker Button pattern (31337b8)