# @spark-web/button

> --- title: Button storybookPath: forms-buttons-button--default isExperimentalPackage: true ---

Latest version **5.7.0** (published 2026-07-14) · 0 weekly downloads

## Install

```sh
npm install @spark-web/button
pnpm add @spark-web/button
yarn add @spark-web/button
bun add @spark-web/button
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.7.0 |
| Published | 2026-07-14 |
| First published | 2022-04-20 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 10 |
| Unpacked size | 122.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | brighte, brighte-release-bot |

## Links

- npm: https://www.npmjs.com/package/@spark-web/button
- Repository: https://github.com/brighte-labs/spark-web
- Homepage: https://github.com/brighte-labs/spark-web#readme
- Issues: https://github.com/brighte-labs/spark-web/issues
- npm.io page: https://npm.io/package/@spark-web/button

## Dependencies (10)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.25.0
- [@emotion/react](https://npm.io/package/@emotion/react.md) ^11.14.0
- [@spark-web/box](https://npm.io/package/@spark-web/box.md) ^6.0.1
- [@spark-web/a11y](https://npm.io/package/@spark-web/a11y.md) ^5.3.0
- [@spark-web/icon](https://npm.io/package/@spark-web/icon.md) ^5.1.0
- [@spark-web/link](https://npm.io/package/@spark-web/link.md) ^5.1.0
- [@spark-web/text](https://npm.io/package/@spark-web/text.md) ^5.3.1
- [@spark-web/theme](https://npm.io/package/@spark-web/theme.md) ^5.13.0
- [@spark-web/utils](https://npm.io/package/@spark-web/utils.md) ^5.1.0
- [@spark-web/spinner](https://npm.io/package/@spark-web/spinner.md) ^5.1.1

## Recent versions

- 5.7.0 (latest) — 2026-07-14
- 0.0.0-snapshot-release-20260827022754 (snapshot-release) — 2026-08-27
- 5.6.0-rc.0 (rc) — 2025-07-24
- 1.5.4-poc-simple.0 (poc-simple) — 2024-12-02
- 0.0.0-snapshot-release-20260715060700 — 2026-07-15
- 0.0.0-snapshot-release-20260715033212 — 2026-07-15
- 5.6.1 — 2026-04-14
- 0.0.0-snapshot-release-20260409073509 — 2026-04-09
- 0.0.0-snapshot-release-20260409063015 — 2026-04-09
- 0.0.0-snapshot-release-20260409051926 — 2026-04-09
- 0.0.0-snapshot-release-20260409001813 — 2026-04-09
- 5.6.0 — 2026-01-15
- 5.5.3 — 2025-10-24
- 5.5.2 — 2025-10-20
- 5.5.0 — 2025-06-26
- … 65 more at https://npm.io/package/@spark-web/button/versions

## README

---
title: Button
storybookPath: forms-buttons-button--default
isExperimentalPackage: true
---

Buttons are clickable elements that are used to trigger actions. They
communicate calls to action to the user and allow users to interact with pages
in a variety of ways. Button labels express what action will occur when the user
interacts with it.

## Tone

Button tones can be broken up into two types; decorative and semantic.

For destructive actions like “delete” you should use the semantic `tone` of
`critical`.

For buttons that have no semantic action type (more common on marketing pages)
use one of our decorative `tones`.

Defaults to `primary`.

```jsx live
<Stack gap="large">
  <Text weight="semibold">Decorative tones</Text>
  <Inline gap="small">
    <Button tone="primary">Primary</Button>
    <Button tone="secondary">Secondary</Button>
  </Inline>
  <Divider />
  <Text weight="semibold">Semantic tones</Text>
  <Inline gap="small">
    <Button tone="neutral">Neutral</Button>
    <Button tone="positive">Positive</Button>
    <Button tone="critical">Critical</Button>
  </Inline>
</Stack>
```

## Prominence

The appearance of the button can be customised with the prominence prop. Valid
options are: `low` and `high`.

Defaults to `high`.

```jsx live
const baseButtonTones = [
  { label: 'Primary', tone: 'primary' },
  { label: 'Secondary', tone: 'secondary' },
  { label: 'Neutral', tone: 'neutral' },
  { label: 'Positive', tone: 'positive' },
  { label: 'Critical', tone: 'critical' },
];

const extraButtonTones = [
  { label: 'Caution', tone: 'caution' },
  { label: 'Informative', tone: 'info' },
];

return (
  <Stack gap="large" dividers>
    <Stack gap="large">
      <Text weight="semibold">High prominence</Text>
      <Inline gap="small">
        {baseButtonTones.map(({ label, tone }) => (
          <Button key={label} tone={tone} prominence="high">
            <LightBulbIcon />
            {label}
          </Button>
        ))}
      </Inline>
    </Stack>
    <Stack gap="large">
      <Text weight="semibold">Low prominence</Text>
      <Inline gap="small">
        {baseButtonTones.concat(extraButtonTones).map(({ label, tone }) => (
          <Button key={label} tone={tone} prominence="low">
            <LightBulbIcon />
            {label}
          </Button>
        ))}
      </Inline>
    </Stack>
    <Stack gap="large">
      <Text weight="semibold">None prominence</Text>
      <Inline gap="small">
        {baseButtonTones.concat(extraButtonTones).map(({ label, tone }) => (
          <Button key={label} tone={tone} prominence="none">
            <LightBulbIcon />
            {label}
          </Button>
        ))}
      </Inline>
    </Stack>
  </Stack>
);
```

## Size

Buttons are available in three sizes: `small`, `medium` and `large`.

Defaults to `medium`. The `small` size (32px tall) is intended for dense
internal-admin surfaces such as table row actions and toolbars — prefer `medium`
everywhere else.

```jsx live
<Inline gap="small">
  <Button size="small">Small</Button>
  <Button size="medium">Medium</Button>
  <Button size="large">Large</Button>
</Inline>
```

## Icons

Icons can be placed next to labels to both clarify an action and call attention
to a button.

```jsx live
<Inline gap="small">
  <Button>
    <DownloadIcon />
    Download
  </Button>
  <Button tone="critical">
    <TrashIcon />
    Delete
  </Button>
</Inline>
```

### Icon only

When using buttons that contain only an icon, you must provide a `label` for
users of assistive technology.

```jsx live
<Inline gap="small">
  <Button label="Download PDF">
    <DownloadIcon />
  </Button>
  <Button tone="critical" label="Delete item">
    <TrashIcon />
  </Button>
  <Button tone="neutral" label="Dismiss">
    <XIcon size="xxsmall" />
  </Button>
</Inline>
```

## Loading

Buttons have an optional `loading` prop to indicate that an action is in
progress. When this is true a spinner will be displayed.

Note: buttons will not be interative when `loading` is true.

```jsx live
const [loading, setLoading] = React.useState(false);
const toggle = event => setLoading(event.target.checked);

return (
  <Stack gap="large">
    <Checkbox size="medium" checked={loading} onChange={toggle}>
      <Text>Toggle loading state</Text>
    </Checkbox>
    <Inline gap="large">
      <Button label="Download" loading={loading}>
        <DownloadIcon />
      </Button>
      <Button loading={loading}>
        <DownloadIcon />
        Download
      </Button>
    </Inline>
    <Inline gap="large">
      <Button label="Download" size="large" loading={loading}>
        <DownloadIcon />
      </Button>
      <Button size="large" loading={loading}>
        <DownloadIcon />
        Download
      </Button>
    </Inline>
  </Stack>
);
```

## ButtonLink

The appearance of a button, with the semantics of a link — shares `Button` API,
with the exception of `href` vs `onClick` props.

```jsx live
<Text>
  <ButtonLink href="#">Visually a link, with button semantics</ButtonLink>
</Text>
```

## BaseButton

Unstyled button primitive that:

- Forwards the button ref
- Provides a default type of `button` (so it doesn't accidently submit forms if
  left off)
- Prevents `onClick` from firing when disabled without disabling the button
- Forces focus of the underlying button when clicked (to address a bug in
  Safari)

## Button Props

<PropsTable displayName="Button" />

## Button Link Props

<PropsTable displayName="ButtonLink" />

---
_Source: https://npm.io/package/@spark-web/button · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._