# 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 `<fieldset>` with a native `<legend>` and native checkbox inputs inside wrapping `<label>` elements, so the group keeps its semantics without requiring classed wrappers.

## 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

```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.

The group should use native `<fieldset>` and `<legend>` elements so assistive technology announces the shared question and each option in context.

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: The group stacks options with shared layout theme spacing rather than component-specific density values.
- CHK-002: Each option keeps native checkbox rendering and browser interaction while the accent color follows the shared primary token.
- 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>` for related checkbox questions instead of a plain container and heading.
- 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`