## Overview An `` 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 attention-getting needs. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/button?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/button) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/button?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/button) [![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-rgg7nx1d) ```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'; ``` ### Anatomy ```html Try me ``` #### 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 label can be provided via the `label` attribute on an `` or on an `` element child to appropriately fulfill the accessibility contract of the button. Label only ```html demo Label only ``` Icon + label ```html demo Icon + Label ``` SVG Icon + label ```html demo SVG Icon + Label ``` Icon only ```html demo ``` ### Options #### Sizes Small ```html demo Small ``` Medium ```html demo Medium ``` Large ```html demo Large ``` Extra Large ```html demo Extra Large ``` #### 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`. They display as follows: Accent ```html demo Label only Icon + Label ``` Primary ```html demo Label only Icon + Label ``` Secondary ```html demo Label only Icon + Label ``` Negative ```html demo Label only Icon + Label ``` #### Treatment The `treatment` attribute accepts `fill` and `outline` as values, and defaults to `fill`. These display as follows: Fill ```html demo Primary, Fill Secondary, Fill Negative, Fill ``` Outline ```html demo Primary, Outline Secondary, Outline Negative, Outline ``` Outline, black ```html demo Label only Icon + Label ``` Outline, white ```html demo Label only Icon + Label ``` ### States 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 Normal Disabled ``` #### 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 Normal Pending ``` ### Behaviors #### Handling events Events handlers for clicks and other user actions can be registered on a `` as one would on a standard HTML `