# Checkbox

> Package `@umriss-ui/core`, version 0.40.0. Demo page: <https://romanhaendler.github.io/umriss-ui/core/checkbox/>. Every page in one line: [llms.txt](https://romanhaendler.github.io/umriss-ui/core/llms.txt); every page in full: [llms-full.txt](https://romanhaendler.github.io/umriss-ui/core/llms-full.txt).

A yes or no that counts when the form is saved (tick box). It also shows the mixed state of a parent whose children are partly checked.

```ts
import { Checkbox } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/checkbox/

The mixed state is derived, never stored: set it when some children are checked, and a click on the parent checks all or none.

## Examples

### Checkbox

A `label` beside the box makes the whole line clickable; the value counts when the form is saved.

```tsx
import { Checkbox } from "@umriss-ui/core";

export default function CheckboxExample() {
  return <Checkbox label="Signature required on delivery" defaultChecked />;
}
```

### States

Unchecked, checked and mixed, each also `disabled`; an `error` on the surrounding `FormField` marks the box invalid.

```tsx
import { Checkbox, FormField, Grid, Stack } from "@umriss-ui/core";

export default function States() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={3}>
        <Checkbox label="Leave at the door" />
        <Checkbox label="Fragile" defaultChecked />
        <Checkbox label="All parcels of the tour" indeterminate />
      </Stack>
      <Stack gap={3}>
        <Checkbox label="Cash on delivery" disabled />
        <Checkbox label="Proof of delivery photo" disabled defaultChecked />
        <Checkbox label="Hazardous goods" disabled indeterminate />
      </Stack>
      <Stack gap={3}>
        <FormField label="Terms" error="Accept the carrier terms to book the pick-up.">
          <Checkbox label="I accept the carrier terms" />
        </FormField>
        <Checkbox label="Call the consignee thirty minutes before arrival, and again from the kerb if nobody answers the door on the first ring" />
      </Stack>
    </Grid>
  );
}
```

### Select all with a mixed state

Derive `indeterminate` from the children when some are checked; a click on the parent checks all or none.

```tsx
import { useState } from "react";
import { Checkbox, Stack } from "@umriss-ui/core";

const TEAM = ["Maya Lindgren", "Arjun Mehta", "Chloe Durand", "Noah Fischer", "Eva Novak"];

export default function SelectAllWithAMixedState() {
  const [notified, setNotified] = useState([true, false, true, false, false]);
  const all = notified.every(Boolean);
  const none = notified.every((on) => !on);

  return (
    <Stack gap={3} align="flex-start">
      <Checkbox
        label="Tell team Web about my leave"
        checked={all}
        indeterminate={!all && !none}
        onChange={(event) => setNotified(notified.map(() => event.target.checked))}
      />
      <Stack gap={2} style={{ paddingLeft: "var(--u-space-6)" }}>
        {TEAM.map((name, i) => (
          <Checkbox
            key={name}
            label={name}
            checked={notified[i]}
            onChange={(event) =>
              setNotified((previous) => previous.map((on, j) => (i === j ? event.target.checked : on)))
            }
          />
        ))}
      </Stack>
    </Stack>
  );
}
```

## When to use something else

- A setting that takes effect the moment it flips → Switch
- One choice out of a few that exclude each other → RadioGroup

## Keyboard

| Key | Action |
|---|---|
| `Space` | Checks or unchecks the focused box. |

## API

### `CheckboxProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `ReactNode` | — | Label to the right of the checkbox.<br>Shown in: [Configurator](https://romanhaendler.github.io/umriss-ui/core/checkbox/#configurator-checkbox), [Checkbox](https://romanhaendler.github.io/umriss-ui/core/checkbox/#checkbox), [States](https://romanhaendler.github.io/umriss-ui/core/checkbox/#states) and 10 more |
| `indeterminate` | `boolean` | `false` | Partially checked (e.g. "select all" with a mixed selection).<br>Shown in: [Configurator](https://romanhaendler.github.io/umriss-ui/core/checkbox/#configurator-checkbox), [States](https://romanhaendler.github.io/umriss-ui/core/checkbox/#states), [Select all with a mixed state](https://romanhaendler.github.io/umriss-ui/core/checkbox/#select-all-with-a-mixed-state) |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](https://romanhaendler.github.io/umriss-ui/core/sizes/#a-row-that-holds-still), [An anchored surface (Popover)](https://romanhaendler.github.io/umriss-ui/core/popover/#anchored-surface), [Take the width of the trigger (Popover)](https://romanhaendler.github.io/umriss-ui/core/popover/#width-from-anchor) and 2 more |

Also takes every attribute of `<input>` – without `size`, `type`.