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 atte
npm install @spectrum-web-components/buttonAn
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.
``zsh`
yarn add @spectrum-web-components/button
Import the side effectful registration of as follows:
`ts`
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:
`ts`
import { Button } from '@spectrum-web-components/button';
`html`
#### Content
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 labellabel
can be provided via the attribute on an
or on an element child to appropriately
fulfill the accessibility contract of the button.
`html demo`
`html demo`
Icon + Label
`html demo`
viewBox="0 0 36 36"
focusable="false"
aria-hidden="true"
role="img"
>
>
SVG Icon + Label
`html demo`
#### Sizes
`html demo`
`html demo`
`html demo`
`html demo`
#### Variants
There are many button variants to choose from in Spectrum. The variant
attribute defaults to , but also accepts the following value: accent, primary, secondary, negative. They display as follows:
`html demo`
Icon + Label
`html demo`
Icon + Label
`html demo`
Icon + Label
`html demo`
Icon + Label
#### Treatment
The treatment attribute accepts fill and outline as values, and defaults to fill. These display as follows:
`html demo`
`html demo`
Primary, Outline
Secondary, Outline
Negative, Outline
`html demo`
>
Icon + Label
static-color="black"
label="Icon only"
icon-only
>
`html demo`
>
Icon + Label
static-color="white"
label="Icon only"
icon-only
>
In addition to the variant, elements support two different visual states, disabled and pending, which can be applied by adding the attribute disabled or pending respectively. All variants support these states.
#### Disabled
While disabled, elements will not respond to click events and will appear faded.
`html`
#### Pending
While in pending state, elements will not respond to click events and will appear faded with an indeterminate .
The element's label and icon will be hidden while in pending state.
Note: The pending state of the 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.
`html`
#### Handling events
Events handlers for clicks and other user actions can be registered on a as one would on a standard HTML
`html`
In addition to handling events like a native
`html demo`
target="_blank"
>
Click me
#### Autofocus
The autofocus attribute sets focus on the when the component
mounts. This is useful for setting focus to a specific sp-button when a
popover or dialog opens.
`html`
#### Include a label
A button is required to have either a visible text label or a label attribute on either the itself
or on an 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.
`html demo
>
Static white on dark background
html demo
>
Click me
Click me
#### 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.