sp-button

NPM

1.1.2

Storybook

View Storybook

Try it on

webcomponents.dev

Examples

API

Changelog

1.1.2 (2025-02-12) #

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

1.1.1 (2025-01-29) #

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

1.1.0 (2025-01-29) #

Bug Fixes #

lock prerelease versions for Spectrum CSS (#5014) (8aa7734)
overlay: make :focus-visible consistent when using overlay type modal (#4912) (7a5f786), closes #5021

1.0.3 (2024-12-09) #

Bug Fixes #

action-button: action-button with href can be perceived by screen reader (#4927) (2a0b3a5)

1.0.1 (2024-11-11) #

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

1.0.0 (2024-10-31) #

BREAKING CHANGES #

remove deprecated 'static' references (#4818)

0.49.0 (2024-10-15) #

Features #

add static-color to replace static (#4808) (43cf086)
button: add noWrap property (#4779) (6760ec2)

0.48.1 (2024-10-01) #

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

0.48.0 (2024-09-17) #

Features #

reactive-controller: new pending state controller (#4605) (68baf94)

0.47.2 (2024-09-03) #

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

0.47.1 (2024-08-27) #

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

0.47.0 (2024-08-20) #

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

0.46.0 (2024-08-08) #

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

0.45.0 (2024-07-30) #

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

0.44.0 (2024-07-15) #

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

0.43.0 (2024-06-11) #

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

0.42.5 (2024-05-24) #

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

0.42.4 (2024-05-14) #

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

0.42.3 (2024-05-01) #

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

0.42.2 (2024-04-03) #

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

0.42.1 (2024-04-02) #

Bug Fixes #

shared: ensure the "updateComplete" in Focusable is stable (885b4a5)

0.42.0 (2024-03-19) #

Bug Fixes #

button: prevent pointer interaction of child/slotted content (2cd5823)
styles, theme: surface exports that omit Spectrum Vars proactively (#4142) (5b524c1)

0.41.2 (2024-03-05) #

Bug Fixes #

button: add missing progress-circle dependency (#4086) (2dfeeb3)

0.41.1 (2024-02-22) #

Bug Fixes #

progress-circle: ensure size can be applied to non-"size" attribute bearing elements (2bc1065)

0.41.0 (2024-02-13) #

Features #

icon: use core tokens (a11ef6b)

0.40.5 (2024-02-05) #

Bug Fixes #

button: use larger icons in Close Button (c4aa02c)

0.40.4 (2024-01-29) #

Bug Fixes #

shared: update and expand attribute coverage in likeAnchor (5cb5f1d)

0.40.3 (2024-01-11) #

Bug Fixes #

button: adds pending button, fixes #3162 (#3163) (71254ec)

0.40.2 (2023-12-18) #

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

0.40.1 (2023-12-05) #

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

0.40.0 (2023-11-16) #

Bug Fixes #

button: support [icon-only] delivery (#3716) (e236a50)

0.39.4 (2023-11-02) #

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

0.39.3 (2023-10-18) #

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

0.39.2 (2023-10-13) #

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

0.39.1 (2023-10-06) #

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

0.39.0 (2023-09-25) #

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

0.38.0 (2023-09-05) #

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

0.37.0 (2023-08-18) #

Bug Fixes #

handle longpress and over filter overlays (483e52d)

0.36.0 (2023-08-18) #

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

0.35.0 (2023-07-31) #

Features #

action-bar: use core tokens (4e21edf)

0.34.0 (2023-07-11) #

Bug Fixes #

added role for href button (5a4ad98)
text fixes (0121fd6)

0.33.2 (2023-06-14) #

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

0.33.0 (2023-06-08) #

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

0.32.0 (2023-06-01) #

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

0.31.0 (2023-05-17) #

Bug Fixes #

shared: allow "disabled" first to return to "tabindex=0" in "focusable" (160bc59)

0.30.0 (2023-05-03) #

Bug Fixes #

add t-shirt sizing to Thumbnail and support for "xxs"/"xs" sizes (520a642)
allow rendered anchors to be aria-hidden (2e9aa23)
allow sp-dropdown to accept focus visibly from sp-field-label (134bafc)
button: add "toggles" attribute to action button (3e2d80c)
button: add excludeSourceSelector to reduce duplication of styles (683e88e)
button: add multiple ui icon imports to sp-button (2f17fa9)
button: allow element content in the default/label slot (7b0ef58)
button: apply icon as slotted content in action-button styles (3b1487b)
button: clean up clear button for reuse across elements (4c71eb1)
button: delivery hold affordance when attribute available (aecc6fe)
button: include "pointerleave" in management of the "active" state (2e702e4)
button: minor docs spelling fix (a7a1359)
button: no double link clicks (02d576c)
button: prevent default on "space" based activations (708d587)
button: relate to this.href correctly (fade3ea)
button: remove old package export listings (32e8573)
button: revert default "variant" application when missing (fab993e)
button: use slot text observer pattern (a7288c3)
correct @element jsDoc listing across library (c97a632)
correct specificity of webkit appearance work around (f0d06bf)
correctly delivery visuals and mouse interactions for litAnchor and extensions (0ae889a)
docs button variant usage (894282c)
dropdown: correctly support "quiet" variant (2a51a2b)
ensure "click" on "NumpadEnter" key press (450fa01)
ensure browser understandable extensions (f4e59f7)
final prerelease review of canary builds (1fc032f)
implement "emphasized" styles (750bbe7)
include "type" in package.json, generate custom-elements.json (1a8d716)
include default export in the "exports" fields (f32407d)
include the "types" entry in package.json files (b432f59)
match "pointerup" listeners with "pointercancel" for full coverage (7f2ce92)
prevent default hoisting of custom pseudo elements (7f66346)
remove errant readme content, correct icon selector (3dd1fb1)
shared: make Focusable pass disabled always (a339d6f)
stop merging selectors in a way that alters the cascade (369388f)
update consumption of Spectrum CSS for latest version (ed2305b)
update file path access (8898bf7)
update latest Spectrum CSS beta releases (d8d3acc)
update role application logic to not overwrite menu* roles (94b6aec)
update to latest spectrum-css packages (a5ca19f)
updating spectrum-config to support new label styles (cefeaad)
use icons without "size" values (3fc7c91)
use the "browsers" listing in postcss-preset-env (4eaf6a2)
work around icon positioning error in CSS source (ef5271c)

Features #

action-button: add action button pattern (03ac00a)
action-group: add action-group pattern (d2de766)
action-group: manage "one" and "multiple" selections (6fad59e)
add and use icons-ui package (d9c3ab2)
add dialog, dialog-wrapped, and underlay elements (3df9050)
adopt DNA@7 base Spectrum CSS (e08cafd)
allow activation of longpress content (55e71fd)
apply sizedMixin for t-shirt sizing (d7b63fb)
button-group: add ButtonGroup pattern (c4d85b5)
button: accept update Spectrum Tokens (d6d6db1)
button: action-buttons with icons AND text (aa788b1)
button: add support for "sp-clear-button" (9028b6d)
button: allow icon only buttons (25623d6)
button: move "white" and "black" out of "variant" and into "static" (5cf51df)
button: pass "label" property to "aria-label" (78ae59d)
button: update spectrum css input (7b5b200)
button: use latest @spectrum-css/button beta (b3b20ed)
button: use synthetic button instead of native (49e94bc)
button: using core-tokens for button (a4a6d42)
card: upgrade to Spectrum CSS v3.0.0 (84cf1a9)
close-button: add Close Button pattern (8e9e1ad)
deprecate "icon-right" in buttons as per Spectrum (064a775)
icons-workflow: vend fully registered icon components (941f3a4)
include all Dev Mode files in side effects (f70817c)
leverage "exports" field in package.json (321abd7)
leverage latest Spectrum button API (9caf2f6)
search: adds sp-search element (d484fc2)
shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
split-button: add split-button pattern (4833a59)
support Spectrum Token consumption and update Action Button to use them (743ab16)
support static white and static black variants of Action Button (7f1e25b)
tabs: add sp-tab-panel element (b17d276)
update lit-* dependencies, wip (377f3c8)
use :focus-visable (via polyfill) instead of :focus (11c6fc7)
use @adobe/spectrum-css@2.15.1 (3918888)
use latest exports specification (a7ecf4b)
use SixedMixin to manage "size" property (8819821)

Performance Improvements #

accept new Spectrum CSS featuring simpler DOM structure (a0b042b)
button: recentralize shared styles in base (85d3d0a)
use "sideEffects" listing in package.json (7271614)
use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts #

Revert "chore: release new versions" (a6d655d)

0.20.5 (2023-04-24) #

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

0.20.4 (2023-04-05) #

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

0.20.3 (2023-03-22) #

Bug Fixes #

prevent default hoisting of custom pseudo elements (7f66346)

Performance Improvements #

accept new Spectrum CSS featuring simpler DOM structure (a0b042b)

0.20.2 (2023-03-08) #

Bug Fixes #

docs button variant usage (894282c)

0.20.1 (2023-02-13) #

Bug Fixes #

button: revert default "variant" application when missing (fab993e)

0.20.0 (2023-02-08) #

Bug Fixes #

updating spectrum-config to support new label styles (cefeaad)
work around icon positioning error in CSS source (ef5271c)

Features #

button: move "white" and "black" out of "variant" and into "static" (5cf51df)
button: using core-tokens for button (a4a6d42)

0.19.10 (2023-01-23) #

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

0.19.9 (2023-01-09) #

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

0.19.8 (2022-12-08) #

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

0.19.7 (2022-11-21) #

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

0.19.6 (2022-11-14) #

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

0.19.5 (2022-10-28) #

Bug Fixes #

button: minor docs spelling fix (a7a1359)

0.19.4 (2022-10-17) #

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

0.19.3 (2022-10-10) #

Bug Fixes #

match "pointerup" listeners with "pointercancel" for full coverage (7f2ce92)

0.19.2 (2022-09-14) #

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

0.19.1 (2022-08-24) #

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

0.19.0 (2022-08-09) #

Features #

include all Dev Mode files in side effects (f70817c)

0.18.1 (2022-08-04) #

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

0.18.0 (2022-07-18) #

Features #

support Spectrum Token consumption and update Action Button to use them (743ab16)

0.17.7 (2022-06-29) #

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

0.17.6 (2022-06-07) #

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

0.17.5 (2022-05-27) #

Bug Fixes #

update consumption of Spectrum CSS for latest version (ed2305b)

0.17.4 (2022-05-12) #

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

0.17.3 (2022-04-21) #

Bug Fixes #

button: add multiple ui icon imports to sp-button (2f17fa9)

0.17.2 (2022-03-30) #

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

0.17.1 (2022-03-08) #

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

0.17.0 (2022-03-04) #

Features #

close-button: add Close Button pattern (8e9e1ad)
leverage latest Spectrum button API (9caf2f6)
support static white and static black variants of Action Button (7f1e25b)

0.16.4 (2022-02-22) #

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

0.16.3 (2022-01-26) #

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

0.16.2 (2022-01-07) #

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

0.16.1 (2021-12-13) #

Bug Fixes #

add t-shirt sizing to Thumbnail and support for "xxs"/"xs" sizes (520a642)

0.16.0 (2021-11-08) #

Features #

update lit-* dependencies, wip (377f3c8)

0.15.1 (2021-11-08) #

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

0.15.0 (2021-11-02) #

Features #

adopt DNA@7 base Spectrum CSS (e08cafd)

0.14.9 (2021-10-12) #

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

0.14.8 (2021-09-20) #

Bug Fixes #

ensure "click" on "NumpadEnter" key press (450fa01)

0.14.7 (2021-09-13) #

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

0.14.6 (2021-08-24) #

Bug Fixes #

correct @element jsDoc listing across library (c97a632)

0.14.5 (2021-08-03) #

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

0.14.4 (2021-07-22) #

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

0.14.3 (2021-07-01) #

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

0.14.2 (2021-06-16) #

Bug Fixes #

update role application logic to not overwrite menu* roles (94b6aec)

0.14.1 (2021-06-07) #

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

0.14.0 (2021-05-24) #

Features #

tabs: add sp-tab-panel element (b17d276)

0.13.7 (2021-05-12) #

Bug Fixes #

allow rendered anchors to be aria-hidden (2e9aa23)

0.13.6 (2021-04-15) #

Bug Fixes #

button: no double link clicks (02d576c)

0.13.5 (2021-04-09) #

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

0.13.4 (2021-03-29) #

Bug Fixes #

button: prevent default on "space" based activations (708d587)

0.13.3 (2021-03-22) #

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

0.13.2 (2021-03-22) #

Bug Fixes #

correctly delivery visuals and mouse interactions for litAnchor and extensions (0ae889a)

0.13.1 (2021-03-05) #

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

0.13.0 (2021-03-04) #

Bug Fixes #

button: include "pointerleave" in management of the "active" state (2e702e4)

Features #

use latest exports specification (a7ecf4b)

0.12.0 (2021-02-11) #

Bug Fixes #

update to latest spectrum-css packages (a5ca19f)

Features #

allow activation of longpress content (55e71fd)

Performance Improvements #

button: recentralize shared styles in base (85d3d0a)

0.11.2 (2021-02-02) #

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

0.11.1 (2021-01-28) #

Bug Fixes #

button: remove old package export listings (32e8573)

0.11.0 (2021-01-21) #

Bug Fixes #

allow sp-dropdown to accept focus visibly from sp-field-label (134bafc)
correct specificity of webkit appearance work around (f0d06bf)
final prerelease review of canary builds (1fc032f)
implement "emphasized" styles (750bbe7)
include the "types" entry in package.json files (b432f59)
stop merging selectors in a way that alters the cascade (369388f)
update file path access (8898bf7)
update latest Spectrum CSS beta releases (d8d3acc)
use icons without "size" values (3fc7c91)
use the "browsers" listing in postcss-preset-env (4eaf6a2)
button: delivery hold affordance when attribute available (aecc6fe)
button: relate to this.href correctly (fade3ea)

Features #

apply sizedMixin for t-shirt sizing (d7b63fb)
deprecate "icon-right" in buttons as per Spectrum (064a775)
use SixedMixin to manage "size" property (8819821)
action-button: add action button pattern (03ac00a)
action-group: manage "one" and "multiple" selections (6fad59e)
button: update spectrum css input (7b5b200)
button: use latest @spectrum-css/button beta (b3b20ed)
button: use synthetic button instead of native (49e94bc)
icons-workflow: vend fully registered icon components (941f3a4)

0.10.0 (2021-01-13) #

Bug Fixes #

final prerelease review of canary builds (1fc032f)
use icons without "size" values (3fc7c91)
button: relate to this.href correctly (fade3ea)
allow sp-dropdown to accept focus visibly from sp-field-label (134bafc)
implement "emphasized" styles (750bbe7)
include the "types" entry in package.json files (b432f59)
stop merging selectors in a way that alters the cascade (369388f)
update file path access (8898bf7)
button: delivery hold affordance when attribute available (aecc6fe)
update latest Spectrum CSS beta releases (d8d3acc)

Features #

apply sizedMixin for t-shirt sizing (d7b63fb)
use SixedMixin to manage "size" property (8819821)
action-button: add action button pattern (03ac00a)
action-group: manage "one" and "multiple" selections (6fad59e)
button: update spectrum css input (7b5b200)
button: use latest @spectrum-css/button beta (b3b20ed)
button: use synthetic button instead of native (49e94bc)
icons-workflow: vend fully registered icon components (941f3a4)

0.9.4 (2020-10-12) #

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

0.9.3 (2020-10-12) #

Bug Fixes #

include default export in the "exports" fields (f32407d)

0.9.2 (2020-09-25) #

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

0.9.1 (2020-09-14) #

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

0.9.0 (2020-08-31) #

Features #

action-group: add action-group pattern (d2de766)
card: upgrade to Spectrum CSS v3.0.0 (84cf1a9)
split-button: add split-button pattern (4833a59)

0.8.4 (2020-08-19) #

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

0.8.3 (2020-07-27) #

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

0.8.2 (2020-07-24) #

Bug Fixes #

ensure browser understandable extensions (f4e59f7)

0.8.1 (2020-07-22) #

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

0.8.0 (2020-07-17) #

Features #

leverage "exports" field in package.json (321abd7)

0.7.0 (2020-06-08) #

Features #

button-group: add ButtonGroup pattern (c4d85b5)

0.6.0 (2020-05-12) #

Features #

add dialog, dialog-wrapped, and underlay elements (3df9050)

0.5.2 (2020-05-08) #

Bug Fixes #

button: clean up clear button for reuse across elements (4c71eb1)
remove errant readme content, correct icon selector (3dd1fb1)

0.5.1 (2020-04-21) #

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

0.5.0 (2020-04-16) #

Bug Fixes #

button: add excludeSourceSelector to reduce duplication of styles (683e88e)

Features #

add and use icons-ui package (d9c3ab2)

Performance Improvements #

use "sideEffects" listing in package.json (7271614)

0.4.8 (2020-04-10) #

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

0.4.7 (2020-04-07) #

Bug Fixes #

button: add "toggles" attribute to action button (3e2d80c)

0.4.6 (2020-03-11) #

Bug Fixes #

dropdown: correctly support "quiet" variant (2a51a2b)

0.4.5 (2020-02-05) #

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

0.4.4 (2020-02-01) #

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

0.4.3 (2020-01-30) #

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

0.4.2 (2020-01-06) #

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

0.4.1 (2019-12-12) #

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

0.4.0 (2019-12-09) #

Features #

button: add support for "sp-clear-button" (9028b6d)

0.3.2 (2019-12-02) #

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

0.3.1 (2019-11-27) #

Bug Fixes #

include "type" in package.json, generate custom-elements.json (1a8d716)

0.3.0 (2019-11-19) #

Features #

use :focus-visable (via polyfill) instead of :focus (11c6fc7)
use @adobe/spectrum-css@2.15.1 (3918888)

0.2.2 (2019-11-01) #

Bug Fixes #

button: use slot text observer pattern (a7288c3)
shared: make Focusable pass disabled always (a339d6f)

0.2.1 (2019-10-16) #

Bug Fixes #

button: allow element content in the default/label slot (7b0ef58)

0.2.0 (2019-10-14) #

Bug Fixes #

button: apply icon as slotted content in action-button styles (3b1487b)

Features #

button: action-buttons with icons AND text (aa788b1)
button: allow icon only buttons (25623d6)
button: pass "label" property to "aria-label" (78ae59d)
search: adds sp-search element (d484fc2)

Performance Improvements #

use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03) #

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

Attributes and Properties #

Property

Attribute

Type

Default

Description

active

boolean

false

disabled

boolean

false

Disable this control. It will not receive focus or events

download

string | undefined

Causes the browser to treat the linked URL as a download.

href

string | undefined

The URL that the hyperlink points to.

label

string | undefined

An accessible label that describes the component. It will be applied to aria-label, but not visually rendered.

noWrap

no-wrap

boolean

false

Disables text wrapping within the button component's label. Please note that this option is not a part of the design specification and should be used carefully, with consideration of this overflow behavior and the readability of the button's content.

pending

boolean

false

pendingLabel

pending-label

string

'Pending'

quiet

boolean

Style this button to be less obvious

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

string | undefined

The relationship of the linked URL as space-separated link types.

staticColor

static-color

'black' | 'white' | undefined

The static color variant to use for this button.

tabIndex

number

The tab index to apply to this control. See general documentation about the tabindex HTML property

target

'_blank' | '_parent' | '_self' | '_top' | undefined

Where to display the linked URL, as the name for a browsing context (a tab, window, or <iframe>).

treatment

ButtonTreatments

'fill'

The visual treatment to apply to this button.

type

'button' | 'submit' | 'reset'

'button'

The default behavior of the button. Possible values are: `button` (default), `submit`, and `reset`.

variant

ButtonVariants

The visual variant to apply to this button.

Slots #

Name

Description

default slot

text label of the Button

icon

The icon to use for Button

Description #

An <sp-button> represents an action a user can take. sp-buttons can be clicked or tapped to perform an action or to navigate to another page. sp-buttons in Spectrum have several variations for different uses and multiple levels of loudness for various attention-getting needs.

Usage #

yarn add @spectrum-web-components/button

Import the side effectful registration of <sp-button> or <sp-clear-button> as follows:

import '@spectrum-web-components/button/sp-button.js';
import '@spectrum-web-components/button/sp-clear-button.js';
import '@spectrum-web-components/button/sp-close-button.js';

When looking to leverage the Button, ClearButton, or CloseButton base classes as a type and/or for extension purposes, do so via:

import { Button, ClearButton, CloseButton } from '@spectrum-web-components/button';

Sizes #

Small

<sp-button size="s">Small</sp-button>

Medium

<sp-button size="m">Medium</sp-button>

Large

<sp-button size="l">Large</sp-button>

Extra Large

<sp-button size="xl">Extra Large</sp-button>

Content #

<sp-button> elements can be provided a visible label, a label with an icon, or just an icon (a non-visible label can be prived via the label attribute on an <sp-button> or on an <sp-icon*> element child to appropriately fulfill the accessibility contract of the button). An icon is provided by placing an icon element to the icon slot.

<sp-button-group>
    <sp-button variant="primary">Label only</sp-button>
    <sp-button variant="primary">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button variant="primary">
        <svg
            slot="icon"
            viewBox="0 0 36 36"
            focusable="false"
            aria-hidden="true"
            role="img"
        >
            <path
                d="M16 36a4.407 4.407 0 0 0 4-4h-8a4.407 4.407 0 0 0 4 4zm9.143-24.615c0-3.437-3.206-4.891-7.143-5.268V3a1.079 1.079 0 0 0-1.143-1h-1.714A1.079 1.079 0 0 0 14 3v3.117c-3.937.377-7.143 1.831-7.143 5.268C6.857 26.8 2 26.111 2 28.154V30h28v-1.846C30 26 25.143 26.8 25.143 11.385z"
            ></path>
        </svg>
        SVG Icon + Label
    </sp-button>
    <sp-button variant="primary" label="Icon only" icon-only>
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Variants #

There are many button variants to choose from in Spectrum. The variant attribute defaults to accent but also accepts the following value: accent, primary, secondary, negative, white, and black. They display as follows:

Accent

<sp-button-group style="min-width: max-content">
    <sp-button variant="accent">Label only</sp-button>
    <sp-button variant="accent">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button variant="accent" label="Icon only" icon-only>
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Primary

<sp-button-group style="min-width: max-content">
    <sp-button variant="primary">Label only</sp-button>
    <sp-button variant="primary">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button variant="primary" label="Icon only" icon-only>
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Secondary

<sp-button-group style="min-width: max-content">
    <sp-button variant="secondary">Label only</sp-button>
    <sp-button variant="secondary">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button variant="secondary" label="Icon only" icon-only>
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Negative

<sp-button-group style="min-width: max-content">
    <sp-button variant="negative">Label only</sp-button>
    <sp-button variant="negative">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button variant="negative" label="Icon only" icon-only>
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Black

<sp-button-group style="min-width: max-content">
    <sp-button static-color="black">Label only</sp-button>
    <sp-button static-color="black">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button static-color="black" label="Icon only" icon-only>
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

White

<sp-button-group style="min-width: max-content">
    <sp-button static-color="white">Label only</sp-button>
    <sp-button static-color="white">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button static-color="white" label="Icon only" icon-only>
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Treatment #

The treatment attribute accepts fill and outline as values, and defaults to fill. These display as follows:

Fill

<sp-button-group style="min-width: max-content">
    <sp-button treatment="fill" variant="primary">Primary, Fill</sp-button>
    <sp-button treatment="fill" variant="secondary">Secondary, Fill</sp-button>
    <sp-button treatment="fill" variant="negative">Negative, Fill</sp-button>
</sp-button-group>

Outline

<sp-button-group style="min-width: max-content">
    <sp-button treatment="outline" variant="primary">
        Primary, Outline
    </sp-button>
    <sp-button treatment="outline" variant="secondary">
        Secondary, Outline
    </sp-button>
    <sp-button treatment="outline" variant="negative">
        Negative, Outline
    </sp-button>
</sp-button-group>

Outline, black

<sp-button-group
    style="background: var(--spectrum-seafoam-600); padding: 0.5em; min-width: max-content"
>
    <sp-button treatment="outline" static-color="black">Label only</sp-button>
    <sp-button treatment="outline" static-color="black">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button
        treatment="outline"
        static-color="black"
        label="Icon only"
        icon-only
    >
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Outline, white

<sp-button-group
    style="background: var(--spectrum-seafoam-600); padding: 0.5em; min-width: max-content"
>
    <sp-button treatment="outline" static-color="white">Label only</sp-button>
    <sp-button treatment="outline" static-color="white">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button
        treatment="outline"
        static-color="white"
        label="Icon only"
        icon-only
    >
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

States #

In addition to the variant, <sp-button> elements support two different visual states, disabled and pending, which can be applied by adding the attribute disabled or pending respectively. All <sp-button> variants support these states.

Disabled #

While disabled, <sp-button> elements will not respond to click events and will appear faded.

<sp-button-group>
    <sp-button variant="primary">Normal</sp-button>
    <sp-button variant="primary" disabled>Disabled</sp-button>
</sp-button-group>

Pending #

While in pending state, <sp-button> elements will not respond to click events and will appear faded with an indeterminent <sp-progress-circle>. <sp-button> elements label and icon will be hidden while in pending state.

Note: pending state of the <sp-button> element is applied after 1s delay to avoid flashing the pending state for quick actions. You can override the delay by adding custom css var --pending-delay to your css.

<sp-button-group>
    <sp-button variant="primary">Normal</sp-button>
    <sp-button variant="primary" pending>Pending</sp-button>
</sp-button-group>

Handling events #

Events handlers for clicks and other user actions can be registered on a <sp-button> as on a standard HTML <button> element.

<sp-button onclick="spAlert(this, '<sp-button> clicked!')">Click me</sp-button>

In addition to handling events like a native <button> HTML element, one can also use a <sp-button> in place of the <a> HTML element by using the href and optional target attribute.

<sp-button
    href="https://github.com/adobe/spectrum-web-components"
    target="_blank"
>
    Click me
</sp-button>

Autofocus #

The autofocus attribute sets focus to the <sp-button> when the component mounts. This is useful for setting focus to a specific sp-button when a popover or dialog opens.

<sp-button autofocus>Confirm</sp-button>

Spectrum Web Components

sp-button

NPM

1.1.2

Storybook

View Storybook

Try it on

webcomponents.dev

1.1.2 (2025-02-12) #

1.1.1 (2025-01-29) #

1.1.0 (2025-01-29) #

Bug Fixes #

1.0.3 (2024-12-09) #

Bug Fixes #

1.0.1 (2024-11-11) #

1.0.0 (2024-10-31) #

BREAKING CHANGES #

0.49.0 (2024-10-15) #

Features #

0.48.1 (2024-10-01) #

0.48.0 (2024-09-17) #

Features #

0.47.2 (2024-09-03) #

0.47.1 (2024-08-27) #

0.47.0 (2024-08-20) #

0.46.0 (2024-08-08) #

0.45.0 (2024-07-30) #

0.44.0 (2024-07-15) #

0.43.0 (2024-06-11) #

0.42.5 (2024-05-24) #

0.42.4 (2024-05-14) #

0.42.3 (2024-05-01) #

0.42.2 (2024-04-03) #

0.42.1 (2024-04-02) #

Bug Fixes #

0.42.0 (2024-03-19) #

Bug Fixes #

0.41.2 (2024-03-05) #

Bug Fixes #

0.41.1 (2024-02-22) #

Bug Fixes #

0.41.0 (2024-02-13) #

Features #

0.40.5 (2024-02-05) #

Bug Fixes #

0.40.4 (2024-01-29) #

Bug Fixes #

0.40.3 (2024-01-11) #

Bug Fixes #

0.40.2 (2023-12-18) #

0.40.1 (2023-12-05) #

0.40.0 (2023-11-16) #

Bug Fixes #

0.39.4 (2023-11-02) #

0.39.3 (2023-10-18) #

0.39.2 (2023-10-13) #

0.39.1 (2023-10-06) #

0.39.0 (2023-09-25) #

0.38.0 (2023-09-05) #

0.37.0 (2023-08-18) #

Bug Fixes #

0.36.0 (2023-08-18) #

0.35.0 (2023-07-31) #

Features #

0.34.0 (2023-07-11) #

Bug Fixes #

0.33.2 (2023-06-14) #

0.33.0 (2023-06-08) #

0.32.0 (2023-06-01) #

0.31.0 (2023-05-17) #

Bug Fixes #

0.30.0 (2023-05-03) #

Bug Fixes #

Features #

Performance Improvements #

Reverts #

0.20.5 (2023-04-24) #

0.20.4 (2023-04-05) #

0.20.3 (2023-03-22) #

Bug Fixes #

Spectrum
Web Components