sp-action-button

NPM 1.5.0

View Storybook

Try it on webcomponents.dev
Overview API Changelog

Overview

An <sp-action-button> represents an action a user can take.

Usage

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/action-button

Import the side effectful registration of <sp-action-button> via:

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

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

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

Options

Sizes

Extra Small Small Medium 
<sp-action-group size="m">
    <sp-action-button>Edit</sp-action-button>
    <sp-action-button>
        <sp-icon-edit slot="icon"></sp-icon-edit>
        Edit
    </sp-action-button>
    <sp-action-button>
        <sp-icon-edit slot="icon"></sp-icon-edit>
    </sp-action-button>
    <sp-action-button hold-affordance>
        <sp-icon-edit slot="icon"></sp-icon-edit>
    </sp-action-button>
</sp-action-group>
 Large Extra Large

Variants

The <sp-action-button> can be customized with either or both of the emphasized and quiet attributes. These will pair with either or both of the state attributes (selected and disabled) to decide the final visual delivery of the <sp-action-button>. Content addressed to the icon slot can also be provided and will be positioned just before the rest of the the supplied button content.

Default 
<div
    style="display: grid; grid-template-columns: repeat(auto-fill, minmax(210px, 1fr)); gap: 2em;"
>
    <div>
        <sp-field-label for="standard">Default</sp-field-label>
        <sp-action-group id="standard">
            <sp-action-button>Edit</sp-action-button>
            <sp-action-button>
                <sp-icon-edit slot="icon"></sp-icon-edit>
                Edit
            </sp-action-button>
            <sp-action-button>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
            <sp-action-button hold-affordance>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
        </sp-action-group>
    </div>

    <div>
        <sp-field-label for="standard-selected">Selected</sp-field-label>
        <sp-action-group id="standard-selected">
            <sp-action-button selected>Edit</sp-action-button>
            <sp-action-button selected>
                <sp-icon-edit slot="icon"></sp-icon-edit>
                Edit
            </sp-action-button>
            <sp-action-button selected>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
            <sp-action-button selected hold-affordance>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
        </sp-action-group>
    </div>

    <div>
        <sp-field-label for="standard-disabled">Disabled</sp-field-label>
        <sp-action-group id="standard-disabled">
            <sp-action-button disabled>Edit</sp-action-button>
            <sp-action-button disabled>
                <sp-icon-edit slot="icon"></sp-icon-edit>
                Edit
            </sp-action-button>
            <sp-action-button disabled>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
            <sp-action-button disabled hold-affordance>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
        </sp-action-group>
    </div>

    <div>
        <sp-field-label for="standard-disabled-selected">
            Disabled + Selected
        </sp-field-label>
        <sp-action-group id="standard-disabled-selected">
            <sp-action-button disabled selected>Edit</sp-action-button>
            <sp-action-button disabled selected>
                <sp-icon-edit slot="icon"></sp-icon-edit>
                Edit
            </sp-action-button>
            <sp-action-button disabled selected>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
            <sp-action-button disabled selected hold-affordance>
                <sp-icon-edit slot="icon"></sp-icon-edit>
            </sp-action-button>
        </sp-action-group>
    </div>
</div>
 Quiet Emphasized Emphasized + quiet

Behaviors

Action button with hold affordance

The use of the hold-affordance attribute signifies that the <sp-action-button> in question will be delivered with a visual affordance outlining that special interaction with the button will dispatch a longpress event. Via a pointer input, this even will be dispatched when 300ms has passed after a pointerdown event without the presence of a pointerup or pointercancel event. Via the keyboard, an event with a code of Space or or ArrowDown while altKey === true will dispatch the event.

<div
    style="display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 2em;"
>
    <overlay-trigger placement="bottom-start">
        <sp-action-button label="Edit" hold-affordance slot="trigger">
            <sp-icon-edit slot="icon"></sp-icon-edit>
        </sp-action-button>
        <sp-popover slot="longpress-content" dialog tip>
            <p style="color: var(--spectrum-neutral-content-color-default);">
                This content is triggered by the "longpress" interaction.
            </p>
        </sp-popover>
    </overlay-trigger>

    <overlay-trigger placement="top">
        <sp-action-button hold-affordance quiet slot="trigger">
            Show Longpress Content
        </sp-action-button>
        <sp-popover slot="longpress-content" dialog tip>
            <p style="color: var(--spectrum-neutral-content-color-default);">
                This content is triggered by the "longpress" interaction.
            </p>
        </sp-popover>
    </overlay-trigger>

    <overlay-trigger placement="top-end">
        <sp-action-button hold-affordance selected slot="trigger">
            <sp-icon-edit slot="icon"></sp-icon-edit>
            Extended Content with Longpress
        </sp-action-button>
        <sp-popover slot="longpress-content" dialog tip>
            <p style="color: var(--spectrum-neutral-content-color-default);">
                This content is triggered by the "longpress" interaction.
            </p>
        </sp-popover>
    </overlay-trigger>
</div>

Toggles

With the application of the toggles attribute, the button will self manage its selected property on click. When this value is updated, a cancellable change event will be dispatched to inform the parent application.

Default 
<sp-action-button toggles id="toggles-default">Toggle button</sp-action-button>
<sp-action-button toggles selected id="toggles-default">
    Toggle button
</sp-action-button>
 Quiet Emphasized Emphasized + Quiet

Handling events

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

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

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

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

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.

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: #ccffee; padding: 20px">
    <sp-action-button static="black">Click me</sp-action-button>
    <sp-action-button static="black" selected>Click me</sp-action-button>
</div>
 Static white on dark background

Clearly state the action

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