# @spark-web/checkbox

> --- title: Checkbox storybookPath: forms-checkbox--default isExperimentalPackage: false ---

Latest version **5.1.2** (published 2026-06-15) · 0 weekly downloads

## Install

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

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

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

## Links

- npm: https://www.npmjs.com/package/@spark-web/checkbox
- 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/checkbox

## Dependencies (9)

- [@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.0
- [@spark-web/a11y](https://npm.io/package/@spark-web/a11y.md) ^5.3.1
- [@spark-web/icon](https://npm.io/package/@spark-web/icon.md) ^5.1.1
- [@spark-web/field](https://npm.io/package/@spark-web/field.md) ^5.3.0
- [@spark-web/stack](https://npm.io/package/@spark-web/stack.md) ^5.1.0
- [@spark-web/theme](https://npm.io/package/@spark-web/theme.md) ^5.13.2
- [@spark-web/control-label](https://npm.io/package/@spark-web/control-label.md) ^5.1.0

## Recent versions

- 5.1.2 (latest) — 2026-06-15
- 0.0.0-snapshot-release-20260827022754 (snapshot-release) — 2026-08-27
- 5.1.0-rc.0 (rc) — 2025-07-24
- 5.1.1 — 2026-05-08
- 5.1.0 — 2026-01-15
- 5.0.5 — 2025-10-31
- 5.0.4 — 2025-10-20
- 5.0.2 — 2025-03-20
- 5.0.1 — 2025-03-16
- 5.0.0 — 2025-02-10
- 5.0.0-rc.31 — 2025-02-10
- 5.0.0-rc.29 — 2025-02-06
- 5.0.0-rc.28 — 2025-02-06
- 5.0.0-rc.27 — 2025-02-05
- 5.0.0-rc.26 — 2025-02-05
- … 37 more at https://npm.io/package/@spark-web/checkbox/versions

## README

---
title: Checkbox
storybookPath: forms-checkbox--default
isExperimentalPackage: false
---

Checkboxes are used to toggle between checked and unchecked states — usually in
a form. If only one option from a list is allowed to be enable, consider using a
`RadioButton` instead.

## Examples

### Controlled

Checkboxes can be both controlled and uncontrolled. To control a checkbox
provide the `checked` state with a value you control, as well as an `onChange`
function to set the new value when the checkbox is toggled.

```jsx live
const [checked, setChecked] = React.useState(false);

return (
  <Stack gap="large">
    <Checkbox
      checked={checked}
      onChange={event => setChecked(event.target.checked)}
    >
      <Text>{checked ? 'Hide' : 'Show'} message</Text>
    </Checkbox>
    {checked && <Text>Toggle the checkbox to hide this message</Text>}
  </Stack>
);
```

### Size

Checkboxes are available in two sizes: `small` and `medium`.

```jsx live
<Stack gap="large">
  <Fieldset legend="Checkbox variations (small)" gap="large">
    <Checkbox size="small" checked={false}>
      Unchecked
    </Checkbox>
    <Checkbox size="small" checked>
      Checked
    </Checkbox>
    <Checkbox size="small" disabled>
      Disabled
    </Checkbox>
    <Checkbox size="small" checked disabled>
      Checked + disabled
    </Checkbox>
  </Fieldset>
  <Divider />
  <Fieldset legend="Checkbox variations (medium)" gap="large">
    <Checkbox size="medium" checked={false}>
      Unchecked
    </Checkbox>
    <Checkbox size="medium" checked>
      Checked
    </Checkbox>
    <Checkbox size="medium" disabled>
      Disabled
    </Checkbox>
    <Checkbox size="medium" checked disabled>
      Checked + disabled
    </Checkbox>
  </Fieldset>
</Stack>
```

### Message and tone

The `message` is used to communicate the status of a field, such as an error
message. This will be announced on focus and can be combined with a `tone` to
illustrate intent. The supported tones are: `critical`, `positive` and
`neutral`.

```jsx live
<Fieldset legend="Message and tone" gap="large">
  <Checkbox message="Critical message" tone="critical">
    Critical
  </Checkbox>
  <Checkbox message="Positive message" tone="positive">
    Positive
  </Checkbox>
  <Checkbox message="Neutral message" tone="neutral">
    Neutral
  </Checkbox>
</Fieldset>
```

## Props

### Checkbox

<PropsTable displayName="Checkbox" />

The `Checkbox` component also extends `InputHTMLAttributes` props and are not
listed here.

### CheckboxPrimitive

<PropsTable displayName="CheckboxPrimitive" />

The `CheckboxPrimitive` component also extends `InputHTMLAttributes` props and
are not listed here.

[data-attribute-map]:
  https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1

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