# Checkbox

**`sonic-checkbox`** is a styled checkbox that writes its `value` into form data. Give it a `name` and a `formDataProvider` (on the field or an ancestor); checkboxes sharing a `name` build an array of the checked values. Label goes in the default slot or `label`, helper text in the `description` slot.

## Basic example

<sonic-code>
  <template>
    <sonic-checkbox>
      Notify me of gate changes
      <span slot="description">One message per change, no spam.</span>
    </sonic-checkbox>
  </template>
</sonic-code>

## Size

With no `size`, the checkbox follows `md` (1rem).

<sonic-code>
  <template>
    <div class="grid gap-2">
      <sonic-checkbox size="2xs">2xs</sonic-checkbox>
      <sonic-checkbox size="xs">xs</sonic-checkbox>
      <sonic-checkbox size="sm">sm</sonic-checkbox>
      <sonic-checkbox>Default</sonic-checkbox>
      <sonic-checkbox size="lg">lg</sonic-checkbox>
      <sonic-checkbox size="xl">xl</sonic-checkbox>
      <sonic-checkbox size="2xl">2xl</sonic-checkbox>
    </div>
  </template>
</sonic-code>

## Checked and disabled

`checked` sets the initial state. `disabled` blocks interaction and dims the control.

<sonic-code>
  <template>
    <div class="grid gap-2">
      <sonic-checkbox checked>Checked</sonic-checkbox>
      <sonic-checkbox disabled>Disabled</sonic-checkbox>
      <sonic-checkbox disabled checked>Disabled and checked</sonic-checkbox>
      <sonic-checkbox>I accept the <sonic-link href="#" class="underline">terms</sonic-link></sonic-checkbox>
    </div>
  </template>
</sonic-code>

## Form binding

Checkboxes with the same `name` under one `formDataProvider` store an array of the checked `value`s. Initial state is read from that data, so a value already present checks the matching box. See [Data flow](/docs/getting-started/dataFlow).

<sonic-code>
  <template>
    <div formDataProvider="checkbox-multiple-demo" class="grid gap-2">
      <sonic-checkbox name="extras" value="baggage" checked>Extra baggage</sonic-checkbox>
      <sonic-checkbox name="extras" value="meal">Meal</sonic-checkbox>
      <sonic-checkbox name="extras" value="lounge">Lounge access</sonic-checkbox>
      <div>Selected: <sonic-value dataProvider="checkbox-multiple-demo" key="extras"></sonic-value></div>
    </div>
  </template>
</sonic-code>

## Single value

`unique` stores a single value instead of an array: checking one box unchecks the others with the same `name`, and the checked box can be unchecked again (value `null`). `radio` does the same but cannot be unchecked by a click.

<sonic-code>
  <template>
    <div formDataProvider="checkbox-unique-demo" class="grid gap-2">
      <sonic-checkbox unique name="cabin" value="economy">Economy</sonic-checkbox>
      <sonic-checkbox unique name="cabin" value="business">Business</sonic-checkbox>
      <div>Cabin: <sonic-value dataProvider="checkbox-unique-demo" key="cabin"></sonic-value></div>
    </div>
  </template>
</sonic-code>

## Check all and indeterminate

A checkbox with `checksAll` and the same `name` toggles every sibling value. It shows the indeterminate icon when only some are checked; its own `value` is never stored. With `unsetOnDisconnect`, a checkbox removes its value from the data when it leaves the DOM. `showAsIndeterminate` forces the indeterminate icon on any checkbox.

<sonic-code>
  <template>
    <div formDataProvider="checkbox-check-all-demo" class="grid gap-2">
      <sonic-checkbox name="alerts" value="all" checksAll>All alerts</sonic-checkbox>
      <sonic-checkbox name="alerts" value="boarding">Boarding</sonic-checkbox>
      <sonic-checkbox name="alerts" value="gate">Gate change</sonic-checkbox>
      <div id="checkbox-removable" class="flex gap-2 items-center">
        <sonic-checkbox name="alerts" value="delay" unsetOnDisconnect>Delay</sonic-checkbox>
        <sonic-button size="xs" variant="ghost" onclick="document.getElementById('checkbox-removable').remove()">Remove</sonic-button>
      </div>
      <div>Selected: <sonic-value dataProvider="checkbox-check-all-demo" key="alerts"></sonic-value></div>
    </div>
  </template>
</sonic-code>

## API reference

| Attribute | Values | Description |
|----------|---------|-------------|
| `name` | string | Key in the form data (dot notation supported) |
| `value` | string | Value stored when checked |
| `formDataProvider` | string | Form data id; inherited from the closest ancestor when omitted |
| `checked` | boolean | Initial checked state |
| `unique` | boolean | Stores a single value; can be unchecked |
| `radio` | boolean | Stores a single value; cannot be unchecked by a click |
| `checksAll` | boolean | Toggles every checkbox with the same `name` |
| `unsetOnDisconnect` | boolean | Removes the value from the data when the element is removed |
| `showAsIndeterminate` | boolean | Forces the indeterminate icon |
| `label` | string (HTML) | Label, rendered before the default slot |
| `description` | string (HTML) | Helper text, rendered in the `description` slot |
| `size` | `2xs` … `2xl` · `inherit` (default `md`) | Font size and box size |
| `disabled` | boolean | Blocks interaction |
| `required` | boolean | Native validation on form submit |
| `autofocus` | boolean | Focuses the input on load |
| `iconName` | string (default `check`) | Icon shown when checked |
| `indeterminateIconName` | string (default `minus-small`) | Icon shown when indeterminate |
| `data-aria-label` · `data-aria-labelledby` | string | Forwarded to the inner input as `aria-label` / `aria-labelledby` |

| Slot | Description |
|------|-------------|
| *(default)* | Label content (text, links) |
| `description` | Helper text under the label |

Fires a `change` event on each click.