# Checkbox

Turns a single independent option on or off.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Checkbox.tsx)

Figma: [Checkbox](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3086-1190)

## Overview

A hidden native input submits its value with the form.

## Examples

### Basic

```tsx
import { Checkbox, Field } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox defaultChecked />
        <Field.Label>Email me receipts</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Basic.tsx)

### Checked

Set `defaultChecked` for an uncontrolled checkbox, or `checked` with `onCheckedChange` to control it.

```tsx
import { Checkbox, Field, style } from '@tempoxyz/ds'

function Item(props: Checkbox.Props & { label: string }) {
  const { label, ...checkbox } = props

  return (
    <Field.Root>
      <Field.Item>
        <Checkbox {...checkbox} />
        <Field.Label>{label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.column()}>
      <Item label="Unchecked" />
      <Item defaultChecked label="Checked" />
    </div>
  )
}

namespace styles {
  export const column = style({ display: 'flex', flexDirection: 'column', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Checked.tsx)

### Indeterminate

Set `indeterminate` to show a minus and expose the mixed state.

```tsx
import { Checkbox, Field } from '@tempoxyz/ds'

function Item(props: Checkbox.Props & { label: string }) {
  const { label, ...checkbox } = props

  return (
    <Field.Root>
      <Field.Item>
        <Checkbox {...checkbox} />
        <Field.Label>{label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return <Item indeterminate label="Indeterminate" />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Indeterminate.tsx)

### Disabled

```tsx
import { Checkbox, Field, style } from '@tempoxyz/ds'

function Item(props: Checkbox.Props & { label: string }) {
  const { label, ...checkbox } = props

  return (
    <Field.Root>
      <Field.Item>
        <Checkbox {...checkbox} />
        <Field.Label>{label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.column()}>
      <Item disabled label="Disabled" />
      <Item defaultChecked disabled label="Disabled checked" />
    </div>
  )
}

namespace styles {
  export const column = style({ display: 'flex', flexDirection: 'column', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Disabled.tsx)

### Size

Set `size` to `small`, `medium` (default), or `large`.

```tsx
import { Checkbox, Field, style } from '@tempoxyz/ds'

function Item(props: Checkbox.Props & { label: string }) {
  const { label, ...checkbox } = props

  return (
    <Field.Root>
      <Field.Item>
        <Checkbox {...checkbox} />
        <Field.Label>{label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.column()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Item defaultChecked key={size} label={size} size={size} />
      ))}
    </div>
  )
}

namespace styles {
  export const column = style({ display: 'flex', flexDirection: 'column', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Size.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Checkbox } from '@tempoxyz/ds'

<Checkbox />
```

## Guidelines

### When to Use

* Offer one independent choice that applies on form submit, such as Email me a receipt for each payment.
* Ask for agreement before a step, such as accepting the API terms before creating a key.
* Select table rows for a bulk action, such as revoking several API keys.

### When Not to Use

* Use [Switch](/docs/components/switch) for a setting that applies immediately.
* Use [CheckboxGroup](/docs/components/checkbox-group) for several related options that share one value array.
* If only one of several options can be chosen, use [RadioGroup](/docs/components/radio-group) or [ChoiceGroup](/docs/components/choice-group).
* If each option needs an icon or a description, use `Choicebox.Checkbox` from [Choicebox](/docs/components/choicebox).

### Choose Checkbox or Switch by When It Applies

* **Checkbox (on submit):** Applies when the form is submitted.
* **Switch (on change):** Applies immediately, such as Payment notifications.

Don't put a [Switch](/docs/components/switch) in a form that ends with Save, or a checkbox in a settings list that saves on change.

### Write the Label as the Checked Statement

**Do:** Describe what happens when the box is checked.

```tsx
/**
 * Do example for "Write the Label as the Checked Statement" on the Checkbox page.
 * Describe what happens when the box is checked.
 * @module
 */
import { Checkbox, Field } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox defaultChecked />
        <Field.Label>Email me a receipt for each payment</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

**Don't:** Write a negative label, where checking the box means don't.

```tsx
/**
 * Don't example for "Write the Label as the Checked Statement" on the Checkbox page.
 * Don't write a negative label, where checking the box means don't.
 * @module
 */
import { Checkbox, Field } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox />
        <Field.Label>Don't email me payment receipts</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

### Make the Label Toggle the Box

Pair the checkbox with `Field.Item` and `Field.Label` from [Field](/docs/components/field), or wrap both in a `<label>`. Pressing the text then toggles the box.

**Do:** Put the checkbox and its `Field.Label` in one `Field.Item`.

```tsx
/**
 * Do example for "Make the Label Toggle the Box" on the Checkbox page.
 * Put the checkbox and its `Field.Label` in one `Field.Item`.
 * @module
 */
import { Checkbox, Field } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox />
        <Field.Label>Email me a receipt for each payment</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

**Don't:** Place plain text beside the box. It neither names nor toggles it.

```tsx
/**
 * Don't example for "Make the Label Toggle the Box" on the Checkbox page.
 * Don't place plain text beside the box. It neither names nor toggles it.
 * @module
 */
import { Checkbox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Checkbox />
      <span>Email me a receipt for each payment</span>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '8' })
}
```

### Use Indeterminate for Partial Selection Only

Inside a [CheckboxGroup](/docs/components/checkbox-group), set `parent` instead and let the group manage the state.

**Do:** Set `indeterminate` on a box that controls others while only some are checked.

```tsx
/**
 * Do example for "Use Indeterminate for Partial Selection Only" on the Checkbox page.
 * Set `indeterminate` on a box that controls others while only some are checked.
 * @module
 */
import { Checkbox, Field, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <Field.Root>
        <Field.Item>
          <Checkbox indeterminate />
          <Field.Label>Select all keys</Field.Label>
        </Field.Item>
      </Field.Root>
      <Field.Root>
        <Field.Item>
          <Checkbox defaultChecked />
          <Field.Label>prod-api-01</Field.Label>
        </Field.Item>
      </Field.Root>
      <Field.Root>
        <Field.Item>
          <Checkbox />
          <Field.Label>staging-api-02</Field.Label>
        </Field.Item>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const list = style({ display: 'flex', flexDirection: 'column', gap: '12' })
}
```

**Don't:** Set `indeterminate` on a box that controls no other boxes.

```tsx
/**
 * Don't example for "Use Indeterminate for Partial Selection Only" on the Checkbox page.
 * Don't set `indeterminate` on a box that controls no other boxes.
 * @module
 */
import { Checkbox, Field } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox indeterminate />
        <Field.Label>Email me a receipt for each payment</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

### Leave Consent Unchecked

If a box must be checked to continue, set `required` and show a `Field.Error` when it is unchecked.

**Do:** Leave boxes that record agreement or opt in to email unchecked.

```tsx
/**
 * Do example for "Leave Consent Unchecked" on the Checkbox page.
 * Leave boxes that record agreement or opt in to email unchecked.
 * @module
 */
import { Checkbox, Field } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox />
        <Field.Label>Email me product updates</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

**Don't:** Preselect consent.

```tsx
/** Don't example for "Leave Consent Unchecked" on the Checkbox page. Don't preselect consent. @module */
import { Checkbox, Field } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox defaultChecked />
        <Field.Label>Email me product updates</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

## Content

* **Explanation:** Put it in a `Field.Description` after the `Field.Item`, in the same `Field.Root`.
* **Links:** Keep them out of the label, where they compete with its press target. Link to terms from the description.

## Accessibility

Follows the [WAI-ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).

### Semantics

* **Control (checkbox):** Reports a checked, unchecked, or mixed state to assistive technology.
* **Native TextInput (input):** A hidden native input submits the value under `name`. Screen readers and Tab skip it.
* **Indeterminate (mixed):** Shows a minus in the box and exposes the mixed state to assistive technology.
* **Disabled (aria-disabled):** Dims the box, blocks changes, and removes it from the tab order.
* **Target Size (36 to 44px):** An invisible hit area extends each indicator past the 24px WCAG 2.2 minimum.

### Keyboard

* **Move to the Checkbox (Tab):** Moves focus to the checkbox. Each one is its own tab stop.
* **Toggle the Checkbox (Space):** Toggles the checkbox between the checked and unchecked states.
* **Submit the Form (Enter):** Submits the owning form without toggling, as a native checkbox does.

### Motion

The check animates in with a slight overshoot. Under `prefers-reduced-motion: reduce`, it fades.

### Your Responsibilities

* **Use ARIA Labels Sparingly (aria-label):** Use it only if the layout already shows the label, such as a table row selector.
* **Explain Disabled Checkboxes:** Say why in nearby text. A disabled checkbox cannot take focus.
* **Pair Invalid With an Error (Field.Error):** An invalid field outlines the box in red. Add an error message to explain it.

## Related

[CheckboxGroup](/docs/components/checkbox-group)

Use for several related checkboxes.

[Switch](/docs/components/switch)

Use for settings that apply immediately.

[Field](/docs/components/field)

Use for the label and description.

[Choicebox](/docs/components/choicebox)

Use for options that need descriptions.

[Forms](/docs/patterns/forms)

Covers placing checkboxes in a form.
