@spectrum-web-components/button

Overview

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. 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> as follows:

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

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

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

Anatomy

<sp-button>Try me</sp-button>

Content

<sp-button> elements can be provided a visible label, a label and an icon, or just an icon.

An icon is provided by placing an icon element in the icon slot.

If the button is icon-only, a non-visible label can be provided via the label attribute on an <sp-button> or on an <sp-icon*> element child to appropriately fulfill the accessibility contract of the button.

Label only

<sp-button variant="primary">Label only</sp-button>

Icon + label

<sp-button variant="primary">
    <sp-icon-help slot="icon"></sp-icon-help>
    Icon + Label
</sp-button>

SVG Icon + label

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

Icon only

<sp-button variant="primary" label="Icon only">
    <sp-icon-help slot="icon"></sp-icon-help>
</sp-button>

Options

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>

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

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 indeterminate <sp-progress-circle>. The <sp-button> element's label and icon will be hidden while in pending state.

Note: The pending state of the <sp-button> element is applied after a 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>

Behaviors

Handling events

Events handlers for clicks and other user actions can be registered on a <sp-button> as one would 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 on 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 id="trigger">Open</sp-button>
<sp-overlay trigger="trigger@click" placement="bottom">
    <sp-popover>
        <!-- Button will autofocus when open -->
        <sp-button autofocus>Confirm</sp-button>
    </sp-popover>
</sp-overlay>

Accessibility

Include a label

A button is required to have either a visible text label or a label attribute on either the <sp-button> itself or on an <sp-icon*> element child.

Don't override color

Do not use custom colors for buttons. The colors of different button variations have been designed to be consistent and accessible.

Don't mix href and non-href buttons in a set of buttons

A screen reader user will not encounter href buttons when navigating by buttons or form controls. While they can both be used in the same page problems could occur if mixing the types in close proximity to each other.

Use static black or static white to contrast with backgrounds and images

To ensure maximum contrast with the background, use static black for light backgrounds and images, and static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast.

Static black on light background

<div
    style="background-color: var(--spectrum-docs-static-black-background-color); padding: 20px"
>
    <sp-button static-color="black">Click me</sp-button>
    <sp-button static-color="black" treatment="outline">Click me</sp-button>
</div>

Static white on dark background

<div
    style="background-color: var(--spectrum-docs-static-white-background-color); padding: 20px"
>
    <sp-button static-color="white">Click me</sp-button>
    <sp-button static-color="white" treatment="outline">Click me</sp-button>
</div>

Clearly state the action

Make sure that a button’s label clearly states the outcome of the action. Use the same word or phrase as found elsewhere in the experience.

Changelog

1.9.0 (2025-10-13)

Minor Changes

sp-icons-workflow: - Upgraded to @adobe/spectrum-css-workflow-icons@5.0.0. - Includes changes from previous a4u upstream releases: - Added S2_Icon_HeartFilled_20_N.svg, updated S2_Icon_SpeedFast_20_N.svg. - Replaced all 22×20px Cloud State icons with 20px variants. - Removed deprecated multi-colored error icon. Added new Cloud State icons (Disconnected, Error, InProgress, Online, Paused, Pending, SlowConnection). - Updated several other icons (CloseCaptions, CommentHide, Community, etc.).

• For the full changelog, see: https://github.com/adobe/spectrum-css-workflow-icons/pull/50

Patch Changes

sp-button: - Fixed: Aria-label handling in <sp-button> component.

• Fixed: Moved aria-label updates to occur after slot content changes are processed to prevent timing issues
• Added: Enhanced label property support for programmatic aria-label control
• Added: Comprehensive tests for aria-label behavior during content and pending state changes
• Fixed: Removed duplicate aria-label update logic in update() method

These changes ensure that aria-labels are properly managed and preserved across component state changes, improving accessibility for screen reader users.

sp-combobox: - Fixed: Pending state handling and accessibility in <sp-combobox> component.

• Changed: Removed dependency on PendingStateController and implemented inline pending state handling
• Fixed: Updated aria-labelledby attribute ordering to improve screen reader experience (label applied-label pending-label)
• Fixed: Updated progress circle implementation to use role="presentation" instead of aria-valuetext
• Added: Direct pending state visual rendering with improved accessibility

These changes improve accessibility for pending states while reducing unnecessary component dependencies.

sp-menu: - Fixed: MenuItem focus stealing from input elements on mouseover by enhancing MenuItem's handleMouseover method to detect when an input element currently has focus and prevent stealing focus in those cases.

sp-alert-dialog: - Fixed: Make the divider color transparent only for Spectrum 2 theme

sp-picker: - Fixed: Picker border color should be hidden in S2 theme

sp-textfield: - Fixed: Update border radius and border width for different t-shirt sizes for textfield component for S2 and Express themes

sp-textfield: - Fixed: Update border color and block padding inside the textfield and textarea components for S2 and Express themes

sp-picker: - Fixed: Pending state handling and accessibility in <sp-picker> component.

• Changed: Removed dependency on PendingStateController and implemented inline pending state handling
• Fixed: Updated aria-labelledby attribute ordering to improve screen reader experience (icon label applied-label pending-label)
• Fixed: Updated progress circle implementation to use role="presentation" instead of aria-valuetext
• Added: Direct pending state visual rendering with improved accessibility

These changes improve accessibility for pending states while reducing unnecessary component dependencies.

sp-progress-circle: - Fixed: Accessibility warning logic in <sp-progress-circle> component.

• Fixed: Updated accessibility warning logic to only apply when role="progressbar" is explicitly set
• Fixed: Improved label validation for better accessibility compliance

These changes ensure accessibility warnings are only shown when appropriate and improve overall accessibility compliance.

sp-reactive-controllers: - Fixed: Accessibility and caching in PendingStateController.

• Fixed: Updated progress circle to use role="presentation" for better accessibility compliance
• Fixed: Improved aria-label caching logic to better handle dynamic label changes
• Added: Documentation noting the controller is primarily used by <sp-button> component
• Fixed: Enhanced caching mechanism to preserve user-set aria-labels during pending states

These changes improve accessibility compliance and aria-label management for components using the pending state controller.

sp-help-text: - Fixed: Update block paddings for S2 and Express themes

sp-field-label: - Fixed: Update block paddings for S2 and Express themes