# Checkbox

A control for turning an option on or off, or for selecting several items from a list. For one choice from a set, use [Radio](/components/radio.md); for a setting that applies immediately, use [Switch](/components/switch.md).

```tsx
// demo.tsx
import {Checkbox, SelectionControlAndLabel} from '@earendil-works/elanor-react';

export default function CheckboxDemo() {
  return (
    <SelectionControlAndLabel
      control={
        <Checkbox.Root defaultChecked>
          <Checkbox.Indicator />
        </Checkbox.Root>
      }
    >
      Include archived projects
    </SelectionControlAndLabel>
  );
}
```

## Usage

```tsx
import {Checkbox, SelectionControlAndLabel} from '@earendil-works/elanor-react';

<SelectionControlAndLabel
  control={
    <Checkbox.Root>
      <Checkbox.Indicator />
    </Checkbox.Root>
  }
>
  Include archived projects
</SelectionControlAndLabel>;
```

[Selection control and label](/components/selection-control-and-label.md) makes the whole label clickable.

## Group

`Checkbox.Group` holds the values of the checked options in one array. Label it with [Fieldset](/components/fieldset.md).

```tsx
// group.tsx
import {Checkbox, Fieldset, SelectionControlAndLabel, Stack} from '@earendil-works/elanor-react';

const protocols = ['HTTP', 'HTTPS', 'SSH'];

export default function CheckboxGroup() {
  return (
    <Fieldset.Root render={<Checkbox.Group defaultValue={['HTTPS']} />}>
      <Fieldset.Legend>Allowed protocols</Fieldset.Legend>
      <Stack gap="small">
        {protocols.map((protocol) => (
          <SelectionControlAndLabel
            key={protocol}
            control={
              <Checkbox.Root value={protocol}>
                <Checkbox.Indicator />
              </Checkbox.Root>
            }
          >
            {protocol}
          </SelectionControlAndLabel>
        ))}
      </Stack>
    </Fieldset.Root>
  );
}
```

## Indeterminate

In a group, a `parent` checkbox checks or clears every option and is indeterminate when only some are checked. Pass every option to the group's `allValues`. Outside a group, set `indeterminate` yourself.

```tsx
// indeterminate.tsx
import {Checkbox, Fieldset, SelectionControlAndLabel, Stack} from '@earendil-works/elanor-react';
import {useState} from 'react';

const projects = ['Website redesign', 'Design system', 'Release notes'];

export default function CheckboxIndeterminate() {
  const [selected, setSelected] = useState(['Design system']);

  return (
    <Fieldset.Root
      render={<Checkbox.Group value={selected} onValueChange={setSelected} allValues={projects} />}
    >
      <Fieldset.Legend>Projects to archive</Fieldset.Legend>
      <Stack gap="small">
        <SelectionControlAndLabel
          control={
            <Checkbox.Root parent>
              <Checkbox.Indicator />
            </Checkbox.Root>
          }
        >
          All projects
        </SelectionControlAndLabel>
        <Stack
          gap="small"
          style={{paddingInlineStart: 'var(--semantic-dimension-space-padding-xx-large)'}}
        >
          {projects.map((project) => (
            <SelectionControlAndLabel
              key={project}
              control={
                <Checkbox.Root value={project}>
                  <Checkbox.Indicator />
                </Checkbox.Root>
              }
            >
              {project}
            </SelectionControlAndLabel>
          ))}
        </Stack>
      </Stack>
    </Fieldset.Root>
  );
}
```

## Disabled

```tsx
// disabled.tsx
import {Checkbox, SelectionControlAndLabel} from '@earendil-works/elanor-react';

export default function CheckboxDisabled() {
  return (
    <SelectionControlAndLabel
      control={
        <Checkbox.Root disabled>
          <Checkbox.Indicator />
        </Checkbox.Root>
      }
    >
      Include deleted projects
    </SelectionControlAndLabel>
  );
}
```

## API

### `Checkbox.Root`

Accepts Base UI [`Checkbox.Root`](https://base-ui.com/react/components/checkbox.md) props.

### `Checkbox.Indicator`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | `true` | Whether to keep the element in the DOM when the checkbox is not checked. |

Also accepts Base UI [`Checkbox.Indicator`](https://base-ui.com/react/components/checkbox.md) props.

### `Checkbox.Group`

Accepts Base UI [`CheckboxGroup`](https://base-ui.com/react/components/checkbox-group.md) props.