sp-button
NPM
0.43.0
Storybook
View Storybook
Try it on
webcomponents.dev
Attributes and Properties #
active
active
boolean
false
disabled
disabled
boolean
false
download
download
string | undefined
href
href
string | undefined
label
label
string | undefined
pending
pending
boolean
false
quiet
quiet
boolean
referrerpolicy
referrerpolicy
| 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | undefined
rel
rel
string | undefined
static
static
'black' | 'white' | undefined
tabIndex
tabIndex
number
target
target
'_blank' | '_parent' | '_self' | '_top' | undefined
treatment
treatment
ButtonTreatments
'fill'
type
type
'button' | 'submit' | 'reset'
'button'
variant
variant
ButtonVariants
Slots #
default slot
icon
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 #
<sp-button size="s">Small</sp-button>
<sp-button size="m">Medium</sp-button>
<sp-button size="l">Large</sp-button>
<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:
<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>
<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>
<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>
<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>
<sp-button-group style="min-width: max-content"> <sp-button static="black">Label only</sp-button> <sp-button static="black"> <sp-icon-help slot="icon"></sp-icon-help> Icon + Label </sp-button> <sp-button static="black" label="Icon only" icon-only> <sp-icon-help slot="icon"></sp-icon-help> </sp-button> </sp-button-group>
<sp-button-group style="min-width: max-content"> <sp-button static="white">Label only</sp-button> <sp-button static="white"> <sp-icon-help slot="icon"></sp-icon-help> Icon + Label </sp-button> <sp-button static="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:
<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>
<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>
<sp-button-group style="background: var(--spectrum-seafoam-600); padding: 0.5em; min-width: max-content" > <sp-button treatment="outline" static="black">Label only</sp-button> <sp-button treatment="outline" static="black"> <sp-icon-help slot="icon"></sp-icon-help> Icon + Label </sp-button> <sp-button treatment="outline" static="black" label="Icon only" icon-only> <sp-icon-help slot="icon"></sp-icon-help> </sp-button> </sp-button-group>
<sp-button-group style="background: var(--spectrum-seafoam-600); padding: 0.5em; min-width: max-content" > <sp-button treatment="outline" static="white">Label only</sp-button> <sp-button treatment="outline" static="white"> <sp-icon-help slot="icon"></sp-icon-help> Icon + Label </sp-button> <sp-button treatment="outline" static="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>
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>