sp-button

Examples

API

Attributes and Properties #

Property	Attribute	Type	Default	Description
`active`	`active`	`boolean`	`false`
`autofocus`	`autofocus`	`boolean`	`false`	When this control is rendered, focus it automatically
`dir`	`dir`	`'ltr' \| 'rtl'`	`'ltr'`
`disabled`	`disabled`	`boolean`	`false`	Disable this control. It will not receive focus or events
`download`	`download`	`string \| undefined`
`href`	`href`	`string \| undefined`
`label`	`label`	`string \| undefined`
`quiet`	`quiet`			Style this button to be less obvious
`rel`	`rel`	`string \| undefined`
`size`	`size`	`ElementSize`
`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`
`treatment`	`treatment`	`ButtonTreatments`	`'fill'`	The visual variant to apply to this button.
`type`	`type`	`'button' \| 'submit' \| 'reset'`	`'button'`
`variant`	`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">
        <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">
        <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">
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Seconday

<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">
        <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">
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Black

<sp-button-group style="min-width: max-content">
    <sp-button variant="black">Label only</sp-button>
    <sp-button variant="black">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button variant="black" label="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 variant="white">Label only</sp-button>
    <sp-button variant="white">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button variant="white" label="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-global-color-seafoam-600); padding: 0.5em; min-width: max-content"
>
    <sp-button treatment="outline" variant="black">Label only</sp-button>
    <sp-button treatment="outline" variant="black">
        <sp-icon-help slot="icon"></sp-icon-help>
        Icon + Label
    </sp-button>
    <sp-button treatment="outline" variant="black" label="Icon only">
        <sp-icon-help slot="icon"></sp-icon-help>
    </sp-button>
</sp-button-group>

Outline, white

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

States #

In addition to the variant, <sp-button> elements have a disabled state visual state which can be applied by adding the attribute disabled. All <sp-button> variants support this. In addition to affectng the visual state, the disabled attribute prevents focus and disallows click events.

<sp-button-group>
    <sp-button variant="primary">Normal</sp-button>
    <sp-button variant="primary" disabled>Disabled</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>

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