1.0.0 • Published 8 months ago

@spectrum-web-components/button v1.0.0

Weekly downloads
837
License
Apache-2.0
Repository
github
Last release
8 months ago

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

<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>
1.0.0-rc.9

8 months ago

1.0.0-rc.7

8 months ago

1.0.0-rc.8

8 months ago

1.0.0-rc.5

8 months ago

1.0.0-rc.6

8 months ago

1.0.0-rc.10

8 months ago

1.0.0-rc.3

8 months ago

1.0.0-rc.4

8 months ago

1.0.0-rc.1

8 months ago

1.0.0-rc.2

8 months ago

0.50.0-beta.11

8 months ago

0.50.0-beta.12

8 months ago

0.50.0-beta.10

8 months ago

1.1.0-beta.1

8 months ago

1.1.0-beta.0

8 months ago

0.50.0-beta.9

8 months ago

0.50.0-beta.8

8 months ago

0.50.0-beta.7

8 months ago

0.50.0-beta.6

8 months ago

0.50.0-beta.5

8 months ago

0.50.0-beta.4

8 months ago

1.0.0

8 months ago

0.50.0-beta.3

8 months ago

0.50.0-beta.2

8 months ago

1.0.0-rc.0

8 months ago

0.50.0-beta.1

8 months ago

0.49.0-beta.2

8 months ago

0.50.0-beta.0

8 months ago

0.49.0

8 months ago

0.49.0-beta.1

8 months ago

0.48.0-beta.0

9 months ago

0.48.0-beta.1

9 months ago

0.48.0-beta.2

9 months ago

0.49.0-beta.0

9 months ago

0.48.1

9 months ago

0.43.0

1 year ago

0.44.0

11 months ago

0.45.0

11 months ago

0.42.5

1 year ago

0.48.0

9 months ago

0.46.0

10 months ago

0.47.1

10 months ago

0.47.2

9 months ago

0.47.0

10 months ago

0.42.4

1 year ago

0.42.3

1 year ago

0.42.2

1 year ago

0.42.1

1 year ago

0.42.0

1 year ago

0.41.2

1 year ago

0.41.1

1 year ago

0.41.0

1 year ago

0.40.5

1 year ago

0.40.4

1 year ago

0.40.3

1 year ago

0.40.2

1 year ago

0.40.1

2 years ago

0.35.1-rc.15

2 years ago

0.35.1-rc.25

2 years ago

0.35.1-rc.26

2 years ago

0.35.1-rc.24

2 years ago

0.38.0

2 years ago

0.35.1-rc.34

2 years ago

0.35.1-rc.43

2 years ago

0.35.1-rc.41

2 years ago

0.39.1

2 years ago

0.39.0

2 years ago

0.39.4

2 years ago

0.39.3

2 years ago

0.39.2

2 years ago

0.36.0

2 years ago

0.40.0

2 years ago

0.37.0

2 years ago

0.34.1-rc.0

2 years ago

0.34.0

2 years ago

0.35.0

2 years ago

0.31.1-react.21

2 years ago

0.32.0

2 years ago

0.31.1-react.3

2 years ago

0.31.1-react.2

2 years ago

0.33.2

2 years ago

0.33.0

2 years ago

0.30.0

2 years ago

0.31.0

2 years ago

0.20.4-overlay.9

2 years ago

0.20.4-overlay.8

2 years ago

0.20.5

2 years ago

0.20.4

2 years ago

0.20.3

2 years ago

0.20.2

2 years ago

0.20.1

2 years ago

0.19.11-react.75

2 years ago

0.20.0

2 years ago

0.19.11-react.49

2 years ago

0.19.11-react.48

2 years ago

0.19.11-react.50

2 years ago

0.19.8-react.54

3 years ago

0.19.11-react.32

2 years ago

0.19.8

3 years ago

0.19.9

2 years ago

0.19.10

2 years ago

0.19.3

3 years ago

0.19.4

3 years ago

0.19.5

3 years ago

0.19.6

3 years ago

0.19.7

3 years ago

0.19.1

3 years ago

0.19.2

3 years ago

0.18.1-devmode.0

3 years ago

0.17.7

3 years ago

0.18.1-devmode.7

3 years ago

0.18.1

3 years ago

0.18.0

3 years ago

0.19.0

3 years ago

0.19.0-devmode.0

3 years ago

0.18.2-devmode.0

3 years ago

0.17.4

3 years ago

0.17.5

3 years ago

0.17.6

3 years ago

0.17.3

3 years ago

0.17.2

3 years ago

0.17.0

3 years ago

0.17.1

3 years ago

0.16.3-express.0

3 years ago

0.16.5-express.9

3 years ago

0.16.3

3 years ago

0.16.4

3 years ago

0.16.2

3 years ago

0.15.1

4 years ago

0.16.0

4 years ago

0.16.1

4 years ago

0.15.0

4 years ago

0.14.9

4 years ago

0.14.8

4 years ago

0.14.7

4 years ago

0.14.6

4 years ago

0.14.6-beta.32

4 years ago

0.14.6-alpha.30

4 years ago

0.14.5

4 years ago

0.14.6-alpha.1

4 years ago

0.14.4

4 years ago

0.14.5-alpha.1

4 years ago

0.14.4-alpha.1

4 years ago

0.14.3

4 years ago

0.14.2

4 years ago

0.14.3-alpha.1

4 years ago

0.14.2-alpha.14

4 years ago

0.14.2-alpha.13

4 years ago

0.14.2-alpha.12

4 years ago

0.14.2-alpha.1

4 years ago

0.14.1

4 years ago

0.14.1-alpha.0

4 years ago

0.14.0

4 years ago

0.13.8-alpha.0

4 years ago

0.13.7

4 years ago

0.13.6

4 years ago

0.13.5

4 years ago

0.13.5-alpha.26

4 years ago

0.13.5-alpha.23

4 years ago

0.13.5-alpha.21

4 years ago

0.13.5-beta.10

4 years ago

0.13.5-beta.11

4 years ago

0.13.5-beta.12

4 years ago

0.13.5-beta.13

4 years ago

0.13.5-beta.14

4 years ago

0.13.5-beta.15

4 years ago

0.13.5-beta.16

4 years ago

0.13.5-beta.17

4 years ago

0.13.5-alpha.17

4 years ago

0.13.5-alpha.10

4 years ago

0.13.5-alpha.12

4 years ago

0.13.5-alpha.11

4 years ago

0.13.5-alpha.9

4 years ago

0.13.4

4 years ago

0.13.3

4 years ago

0.13.2

4 years ago

0.13.1

4 years ago

0.13.0

4 years ago

0.11.3-alpha.33

4 years ago

0.12.0

4 years ago

0.11.2

4 years ago

0.11.1

4 years ago

0.11.0

4 years ago

0.9.5-alpha.178

4 years ago

0.10.0-alpha.40

4 years ago

0.10.0

4 years ago

0.9.5-alpha.169

4 years ago

0.9.5-alpha.84

5 years ago

0.9.5-alpha.85

5 years ago

0.9.5-alpha.60

5 years ago

0.9.4

5 years ago

0.9.4-alpha.0

5 years ago

0.9.3

5 years ago

0.9.3-beta.17

5 years ago

0.9.3-alpha.17

5 years ago

0.9.2

5 years ago

0.9.1

5 years ago

0.9.0

5 years ago

0.8.4-alpha.71

5 years ago

0.8.4

5 years ago

0.8.4-alpha.28

5 years ago

0.8.3

5 years ago

0.8.2

5 years ago

0.8.1

5 years ago

0.8.0

5 years ago

0.7.1-alpha.38

5 years ago

0.7.1-alpha.6

5 years ago

0.7.0

5 years ago

0.6.0

5 years ago

0.5.2

5 years ago

0.5.1

5 years ago

0.5.0

5 years ago

0.4.9-alpha.1

5 years ago

0.4.8

5 years ago

0.4.7

5 years ago

0.4.6

5 years ago

0.4.5

5 years ago

0.4.4

5 years ago

0.4.3

5 years ago

0.4.2

5 years ago

0.4.1

6 years ago

0.4.0

6 years ago

0.3.2

6 years ago

0.3.1

6 years ago

0.3.0

6 years ago

0.2.2

6 years ago

0.2.1

6 years ago

0.2.0

6 years ago

0.1.3

6 years ago

0.1.2

6 years ago

0.1.1

6 years ago

0.1.0

6 years ago

0.0.1

6 years ago