# Checkbox

Status: stable

Turn one option on or off, or pick several from a list.

Checkboxes turn a single option on or off, or let managers pick any number of options from a list. Each checkbox has its own label, and a group of them sits in a fieldset with a legend that asks the question.

Atrium uses the browser's own checkbox, tinted with the accent colour. It has no separate hover style.

## Example

```html
<fieldset class="at-fieldset"><legend>Send reminders by</legend><label class="at-choice"><input type="checkbox" checked /> Email</label><label class="at-choice"><input type="checkbox" /> SMS</label></fieldset>
```

## Anatomy

1. **Legend**: font-size: var(--at-text-sm) /* 14px */; font-weight: var(--at-weight-bold); margin-bottom: var(--at-space-2) /* 4px */

2. **Box**: width: 1.125rem; height: 1.125rem /* 18px */; accent-color: var(--at-bg-primary)

3. **Label**: font-size: var(--at-text-md) /* 16px */; the whole label is clickable

## Size and spacing

- **Box**: 18px by 18px; margin-top: 0.15rem to line up with the first line of text

- **Spacing**: box to label: var(--at-space-3) /* 8px */; between options: var(--at-space-3) /* 8px */

## Variants

### Checkbox group

Pick any number of options. Wrap the group in a fieldset with a legend.

```html
<fieldset class="at-fieldset"><legend>Notify me about</legend><label class="at-choice"><input type="checkbox" checked /> New readings</label><label class="at-choice"><input type="checkbox" /> Missed readings</label><label class="at-choice"><input type="checkbox" /> Price changes</label></fieldset>
```

| State | Specification |

|---|---|

| Unchecked | browser default box |

| Checked | fill: var(--at-bg-primary) |

| Focus | outline: 3px solid var(--at-border-focus); outline-offset: 2px |

| Disabled | greyed by the browser |

### Single checkbox

One option on its own, for a yes or no setting. No fieldset is needed.

```html
<label class="at-choice"><input type="checkbox" /> Include archived properties</label>
```

## When to use

- Choosing any number of options, including none.
- A single yes or no setting that is saved with the form.

## When not to use

- Exactly one choice from a list: use radios.
- A setting that takes effect straight away: use a button.

## Content

- Labels say what is turned on: "Email", "Include archived properties".
- Avoid negatives such as "Do not send reminders".
- The legend asks the question: "Send reminders by".

## Do and don't

Do: A positive label: ticked means on.

```html
<label class="at-choice"><input type="checkbox" checked /> Send reminders</label>
```

Don't: A double negative: ticked means... what?

```html
<label class="at-choice"><input type="checkbox" /> Do not stop sending reminders</label>
```

## Do

- Wrap the input in its label so the text is clickable.

## Don't

- Use a checkbox to trigger an action immediately.

## Code

```html
<fieldset class="at-fieldset">
  <legend>Send reminders by</legend>
  <label class="at-choice"><input type="checkbox" checked /> Email</label>
  <label class="at-choice"><input type="checkbox" /> SMS</label>
</fieldset>
```

## Classes

| Class | What it does |

|---|---|

| `at-fieldset` | Groups related choices |

| `at-choice` | Label wrapping the input and its text |

## Tokens

`--at-bg-primary`

## Accessibility

- Group related checkboxes in a fieldset with a legend.