sp-button

Examples API

Attributes and Properties #

Property Attribute Type Default Description
active active boolean false
quiet quiet Style this button to be less obvious
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 #

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

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