# Checkbox

## Overview

The checkbox component is a multi-select form control for toggling one or more independent options on or off.

The component pattern uses a native checkbox input inside a wrapping `<label>`. A related group of checkboxes uses a native `<fieldset>` and `<legend>` so the shared question is announced in context.

## When to use

Use checkboxes when users may select any number of independent options, including none or all.

## When not to use

Do not use checkboxes when users must choose exactly one option; use radios.

## Usage

For one independent option, use a labeled checkbox without a fieldset:

```html
<label>
  <input type="checkbox" name="include-archived" />
  Include archived results
</label>
```

For multiple options that answer a shared question, group them with a fieldset and legend:

```html
<fieldset>
  <legend>Notifications</legend>
  <label>
    <input type="checkbox" name="notifications" value="email" checked />
    Email updates
  </label>
  <label>
    <input type="checkbox" name="notifications" value="sms" />
    SMS alerts
  </label>
</fieldset>
```

Use this component when the user can select any number of independent options, including none or all of them.

Use radios instead when the user must choose exactly one option from the set.

Do not add a `<fieldset>` only to activate checkbox styling. Use native `<fieldset>` and `<legend>` elements when multiple checkboxes share a question so assistive technology announces that context with each option.

Each checkbox should stay inside its own wrapping `<label>` so the full text remains clickable without extra helper markup.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- CHK-001: A related group stacks options with shared layout theme spacing rather than component-specific density values.
- CHK-002: Each labeled option keeps native checkbox rendering and browser interaction while the accent color follows the shared primary token, whether or not it belongs to a fieldset.
- CHK-003: Disabled options should dim through shared text tokens rather than bespoke disabled colors.
- CHK-004: Focus must remain clearly visible for keyboard users.
## Accessibility

- Use a native `<fieldset>` and `<legend>` when multiple checkboxes answer a related question; a standalone checkbox does not need them.
- Wrap each checkbox in a native `<label>` so the label text enlarges the interactive target.
- Keep option text descriptive enough to make sense when announced on its own.
- Do not replace the native checkbox with custom scripted markup unless the product truly requires behavior the platform cannot provide.
- If helper or error text is needed, place it near the fieldset and associate it with `aria-describedby`.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--checkbox-color-primary` | `<color>` | Sets --checkbox-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-primary-subtle` | `<color>` | Sets --checkbox-color-primary-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-text` | `<color>` | Sets --checkbox-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-text-accent` | `<color>` | Sets --checkbox-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-text-subtle` | `<color>` | Sets --checkbox-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-control-border-width` | `<length>` | Sets --checkbox-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-control-gap` | `<length>` | Sets --checkbox-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-focus-ring-size` | `<length>` | Sets --checkbox-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-font-family-sans` | `Any` | Sets --checkbox-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-font-size` | `<length>` | Sets --checkbox-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-line-height` | `<number>` | Sets --checkbox-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-space-inline` | `<length>` | Sets --checkbox-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-primary`
- `--color-primary-subtle`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-focus-ring-size`
- `--layout-space-inline`