# @spectrum-web-components/picker-button

> Web component implementation of a Spectrum design PickerButton

Latest version **1.12.5** (published 2026-10-14) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @spectrum-web-components/picker-button
pnpm add @spectrum-web-components/picker-button
yarn add @spectrum-web-components/picker-button
bun add @spectrum-web-components/picker-button
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.12.5 |
| Published | 2026-10-14 |
| First published | 2022-10-10 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1576 |
| Author | Adobe |
| Maintainers | caseyisonit, taratadobe, rajrock38, jnjosh, nikkimk, rubenc, jianliao79, pvashish, patrickfulton |
| Keywords | design-system, spectrum, adobe, adobe-spectrum, web components, web-components, lit-element, lit-html, component, css |

## Links

- npm: https://www.npmjs.com/package/@spectrum-web-components/picker-button
- Repository: https://github.com/adobe/spectrum-web-components
- Homepage: https://opensource.adobe.com/spectrum-web-components/components/picker-button
- Issues: https://github.com/adobe/spectrum-web-components/issues
- npm.io page: https://npm.io/package/@spectrum-web-components/picker-button

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 1.12.5 (latest) — 2026-10-14
- 1.12.3-next.20260903033550 (next) — 2026-09-03
- 1.12.3-snapshot-test.20260831180357 (snapshot-test) — 2026-08-31
- 1.12.3-test.20260827122947 (test) — 2026-08-27
- 1.12.0-snapshot.20260422090428 (snapshot) — 2026-04-22
- 1.12.0-snaphot-test.20260223152537 (snaphot-test) — 2026-02-23
- 1.12.0-testing.20260223092154 (testing) — 2026-02-23
- 1.11.0-preview-ae61361d.20251203202755 (preview) — 2025-12-03
- 1.9.1-nightly.20251101120150 (nightly) — 2025-11-01
- 1.6.1-beta.0 (beta) — 2025-05-05
- 0.0.0-20250410163257 (calendar) — 2025-04-10
- 1.0.1-color-testing (color-testing) — 2024-12-09
- 1.0.0-rc.10 (rc) — 2024-10-30
- 1.12.4 — 2026-09-29
- 1.12.3-next.20260901142734 — 2026-09-01
- … 333 more at https://npm.io/package/@spectrum-web-components/picker-button/versions

## README

## 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!](https://img.shields.io/npm/v/@spectrum-web-components/picker-button?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/picker-button)
[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/picker-button?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/picker-button)

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

```html
<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:

```html
<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:

```html
<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">

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

</sp-tab-panel>
<sp-tab value="m">Medium</sp-tab>
<sp-tab-panel value="m">

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

</sp-tab-panel>
<sp-tab value="l">Large</sp-tab>
<sp-tab-panel value="l">

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

</sp-tab-panel>
<sp-tab value="xl">Extra Large</sp-tab>
<sp-tab-panel value="xl">

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

</sp-tab-panel>
</sp-tabs>

#### Rounded

When delivered as part of the `express` system, an `<sp-picker-button>` with the `rounded` attribute will be given deeply rounded corners:

```html
<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:

```html
<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`:

```html
<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:

```html
<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:

```html
<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:

```html
<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`](https://github.com/adobe/spectrum-web-components/blob/main/packages/combobox/src/Combobox.ts). For comprehensive information on menu button accessibility, see WAI ARIA Authoring Practice Guide's [Menu Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/).

```html
<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 <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.

---
_Source: https://npm.io/package/@spectrum-web-components/picker-button · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._