> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# Checkbox

Collects any number of choices from a limited set, or turns a single option on or off — reach for `Radio` when only one choice is allowed, and `Switch` when the change takes effect immediately instead of on submit. Past roughly ten options, a `Select` reads better than a long column of boxes.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/Checkbox) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/inputs-checkbox--overview)

```tsx
import { Checkbox, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';

export const Basic = () => (
  <Checkbox data-testid='checkbox'>
    <CheckboxIndicator />
    <CheckboxLabel>Accept terms and conditions</CheckboxLabel>
  </Checkbox>
);
```

## Usage

```tsx
import { Checkbox, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';
```

## Examples

### Checked

The checked state. Pass `checked` to drive it from your own state, or `defaultChecked` to let the checkbox keep track of it.

```tsx
import { Checkbox, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';

export const Checked = () => (
  <Checkbox checked>
    <CheckboxIndicator />
    <CheckboxLabel>Accept terms and conditions</CheckboxLabel>
  </Checkbox>
);
```

### Indeterminate

`checked='indeterminate'` is for a parent whose children are only partly selected. Set it
deliberately — a click never produces it — and clear it once every child is checked or unchecked.

```tsx
import { Checkbox, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';

export const Indeterminate = () => (
  <Checkbox checked='indeterminate'>
    <CheckboxIndicator />
    <CheckboxLabel>Accept terms and conditions</CheckboxLabel>
  </Checkbox>
);
```

### Disabled

All three states while disabled, so you can see that the indicator stays readable when the option cannot be changed.

```tsx
import { Checkbox, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';
import { VStack } from '@wallarm-org/design-system/Stack';

export const Disabled = () => (
  <VStack>
    <Checkbox disabled>
      <CheckboxIndicator />
      <CheckboxLabel>Accept terms and conditions</CheckboxLabel>
    </Checkbox>

    <Checkbox checked disabled>
      <CheckboxIndicator />
      <CheckboxLabel>Accept terms and conditions</CheckboxLabel>
    </Checkbox>

    <Checkbox checked='indeterminate' disabled>
      <CheckboxIndicator />
      <CheckboxLabel>Accept terms and conditions</CheckboxLabel>
    </Checkbox>
  </VStack>
);
```

### With description

`CheckboxDescription` adds a second line under the label, and switches the row to a grid so that text lines up with the label rather than the box.

```tsx
import { Checkbox, CheckboxDescription, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';
import { Info } from '@wallarm-org/design-system/icons';
import { Tooltip, TooltipContent, TooltipTrigger } from '@wallarm-org/design-system/Tooltip';

export const WithDescription = () => (
  <Checkbox>
    <CheckboxIndicator />
    <CheckboxLabel>
      Accept terms and conditions
      <Tooltip>
        <TooltipTrigger>
          <Info />
        </TooltipTrigger>
        <TooltipContent>Additional information</TooltipContent>
      </Tooltip>
    </CheckboxLabel>
    <CheckboxDescription>
      By clicking this checkbox, you agree to the terms and conditions.
    </CheckboxDescription>
  </Checkbox>
);
```

### Group

`CheckboxGroup` ties several checkboxes to one `name` and one array of values, and owns the spacing
between them. Every box stays independent: ticking one must never move another, unless it is a
parent selecting all of its children.

```tsx
import { Checkbox, CheckboxGroup, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';

export const Group = () => (
  <CheckboxGroup name='framework' defaultValue={['vue']}>
    <Checkbox value='react'>
      <CheckboxIndicator />
      <CheckboxLabel>React</CheckboxLabel>
    </Checkbox>

    <Checkbox value='solid'>
      <CheckboxIndicator />
      <CheckboxLabel>Solid</CheckboxLabel>
    </Checkbox>

    <Checkbox value='vue'>
      <CheckboxIndicator />
      <CheckboxLabel>Vue</CheckboxLabel>
    </Checkbox>

    <Checkbox value='svelte'>
      <CheckboxIndicator />
      <CheckboxLabel>Svelte</CheckboxLabel>
    </Checkbox>
  </CheckboxGroup>
);
```

### Card

`variant='card'` gives every option its own bordered surface. Cards exist to carry a description —
that is what the extra room is for, and a card holding a bare label wastes it. Plain rows read
better for short lists of short labels.

```tsx
import { Checkbox, CheckboxDescription, CheckboxGroup, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';
import { Info } from '@wallarm-org/design-system/icons';
import { Tooltip, TooltipContent, TooltipTrigger } from '@wallarm-org/design-system/Tooltip';

export const Card = () => (
  <CheckboxGroup variant='card' name='framework' defaultValue={['vue', 'angular']}>
    <Checkbox value='react'>
      <CheckboxIndicator />
      <CheckboxLabel>React</CheckboxLabel>
      <CheckboxDescription>
        By clicking this checkbox, you agree to the terms and conditions.
      </CheckboxDescription>
    </Checkbox>

    <Checkbox value='solid'>
      <CheckboxIndicator />
      <CheckboxLabel>
        Solid
        <Tooltip>
          <TooltipTrigger>
            <Info />
          </TooltipTrigger>
          <TooltipContent>Additional information</TooltipContent>
        </Tooltip>
      </CheckboxLabel>
      <CheckboxDescription>
        By clicking this checkbox, you agree to the terms and conditions.
      </CheckboxDescription>
    </Checkbox>

    <Checkbox value='vue'>
      <CheckboxIndicator />
      <CheckboxLabel>Vue</CheckboxLabel>
      <CheckboxDescription>
        By clicking this checkbox, you agree to the terms and conditions.
      </CheckboxDescription>
    </Checkbox>

    <Checkbox value='svelte' disabled>
      <CheckboxIndicator />
      <CheckboxLabel>Svelte</CheckboxLabel>
      <CheckboxDescription>
        By clicking this checkbox, you agree to the terms and conditions.
      </CheckboxDescription>
    </Checkbox>

    <Checkbox value='angular' disabled>
      <CheckboxIndicator />
      <CheckboxLabel>Angular</CheckboxLabel>
      <CheckboxDescription>
        By clicking this checkbox, you agree to the terms and conditions.
      </CheckboxDescription>
    </Checkbox>
  </CheckboxGroup>
);
```

### Form field

Wrapped in `Field`, so the label and description above the options come from `FieldLabel` and `FieldDescription`. Shown as plain rows and as cards.

```tsx
import { Checkbox, CheckboxGroup, CheckboxIndicator, CheckboxLabel } from '@wallarm-org/design-system/Checkbox';
import { Field, FieldDescription, FieldLabel } from '@wallarm-org/design-system/Field';
import { Info } from '@wallarm-org/design-system/icons';
import { HStack } from '@wallarm-org/design-system/Stack';
import { Tooltip, TooltipContent, TooltipTrigger } from '@wallarm-org/design-system/Tooltip';

export const FormField = () => (
  <HStack align='start' gap={40}>
    <Field>
      <FieldLabel>
        Label{' '}
        <Tooltip>
          <TooltipTrigger>
            <Info />
          </TooltipTrigger>
          <TooltipContent>Additional information</TooltipContent>
        </Tooltip>
      </FieldLabel>

      <FieldDescription>This is an input description.</FieldDescription>

      <CheckboxGroup name='framework' defaultValue={['vue']}>
        <Checkbox value='react'>
          <CheckboxIndicator />
          <CheckboxLabel>React</CheckboxLabel>
        </Checkbox>

        <Checkbox value='solid'>
          <CheckboxIndicator />
          <CheckboxLabel>Solid</CheckboxLabel>
        </Checkbox>

        <Checkbox value='vue'>
          <CheckboxIndicator />
          <CheckboxLabel>Vue</CheckboxLabel>
        </Checkbox>

        <Checkbox value='svelte'>
          <CheckboxIndicator />
          <CheckboxLabel>Svelte</CheckboxLabel>
        </Checkbox>
      </CheckboxGroup>
    </Field>

    <Field>
      <FieldLabel>
        Label
        <Tooltip>
          <TooltipTrigger>
            <Info />
          </TooltipTrigger>
          <TooltipContent>Additional information</TooltipContent>
        </Tooltip>
      </FieldLabel>

      <FieldDescription>This is an input description.</FieldDescription>

      <CheckboxGroup variant='card' name='framework' defaultValue={['vue']}>
        <Checkbox value='react'>
          <CheckboxIndicator />
          <CheckboxLabel>React</CheckboxLabel>
        </Checkbox>

        <Checkbox value='solid'>
          <CheckboxIndicator />
          <CheckboxLabel>Solid</CheckboxLabel>
        </Checkbox>

        <Checkbox value='vue'>
          <CheckboxIndicator />
          <CheckboxLabel>Vue</CheckboxLabel>
        </Checkbox>

        <Checkbox value='svelte'>
          <CheckboxIndicator />
          <CheckboxLabel>Svelte</CheckboxLabel>
        </Checkbox>
      </CheckboxGroup>
    </Field>
  </HStack>
);
```

## Props

| Prop            | Type                                                 | Default | Description                                                                                                                    |
| --------------- | ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| title           | `string \| undefined`                                |         |                                                                                                                                |
| defaultValue    | `string \| number \| readonly string[] \| undefined` |         |                                                                                                                                |
| autoFocus       | `boolean \| undefined`                               |         |                                                                                                                                |
| tabIndex        | `number \| undefined`                                |         |                                                                                                                                |
| rel             | `string \| undefined`                                |         |                                                                                                                                |
| onChange        | `ChangeEventHandler<T, Element> \| undefined`        |         |                                                                                                                                |
| htmlFor         | `string \| undefined`                                |         |                                                                                                                                |
| id              | `string`                                             |         | The unique identifier of the machine.                                                                                          |
| form            | `string \| undefined`                                |         | The id of the form that the checkbox belongs to.                                                                               |
| defaultChecked  | `CheckedState \| undefined`                          |         | The initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox. |
| disabled        | `boolean \| undefined`                               |         | Whether the checkbox is disabled                                                                                               |
| name            | `string \| undefined`                                |         | The name of the input field in a checkbox. Useful for form submission.                                                         |
| value           | `string \| undefined`                                |         | The value of checkbox input. Useful for form submission.                                                                       |
| ids             | `ElementIds \| undefined`                            |         | The ids of the elements in the checkbox. Useful for composition.                                                               |
| readOnly        | `boolean \| undefined`                               |         | Whether the checkbox is read-only                                                                                              |
| required        | `boolean \| undefined`                               |         | Whether the checkbox is required                                                                                               |
| onCheckedChange | `complex`                                            |         | The callback invoked when the checked state changes.                                                                           |
| invalid         | `boolean \| undefined`                               |         | Whether the checkbox is invalid                                                                                                |
| checked         | `CheckedState \| undefined`                          |         | The controlled checked state of the checkbox                                                                                   |
| asChild         | `boolean \| undefined`                               |         | Use the provided child element as the default rendered element, combining their props and behavior.                            |
| data-testid     | `string \| undefined`                                |         |                                                                                                                                |

### CheckboxDescription

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| title          | `string \| undefined`                                |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |

### CheckboxGroup

| Prop              | Type                                          | Default   | Description                                                                                         |
| ----------------- | --------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------- |
| title             | `string \| undefined`                         |           |                                                                                                     |
| defaultChecked    | `boolean \| undefined`                        |           |                                                                                                     |
| defaultValue      | `string[] \| undefined`                       |           | The initial value of `value` when uncontrolled                                                      |
| autoFocus         | `boolean \| undefined`                        |           |                                                                                                     |
| id                | `string \| undefined`                         |           |                                                                                                     |
| tabIndex          | `number \| undefined`                         |           |                                                                                                     |
| rel               | `string \| undefined`                         |           |                                                                                                     |
| onChange          | `ChangeEventHandler<T, Element> \| undefined` |           |                                                                                                     |
| disabled          | `boolean \| undefined`                        |           | If `true`, the checkbox group is disabled                                                           |
| name              | `string \| undefined`                         |           | The name of the input fields in the checkbox group (Useful for form submission).                    |
| value             | `string[] \| undefined`                       |           | The controlled value of the checkbox group                                                          |
| asChild           | `boolean \| undefined`                        |           | Use the provided child element as the default rendered element, combining their props and behavior. |
| readOnly          | `boolean \| undefined`                        |           | If `true`, the checkbox group is read-only                                                          |
| invalid           | `boolean \| undefined`                        |           | If `true`, the checkbox group is invalid                                                            |
| onValueChange     | `((value: string[]) => void) \| undefined`    |           | The callback to call when the value changes                                                         |
| maxSelectedValues | `number \| undefined`                         |           | The maximum number of selected values                                                               |
| variant           | `{ default: string; card: string; }`          | `default` |                                                                                                     |

### CheckboxLabel

| Prop           | Type                                                 | Default | Description                                                                                         |
| -------------- | ---------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| title          | `string \| undefined`                                |         |                                                                                                     |
| defaultChecked | `boolean \| undefined`                               |         |                                                                                                     |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |                                                                                                     |
| autoFocus      | `boolean \| undefined`                               |         |                                                                                                     |
| id             | `string \| undefined`                                |         |                                                                                                     |
| tabIndex       | `number \| undefined`                                |         |                                                                                                     |
| rel            | `string \| undefined`                                |         |                                                                                                     |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |                                                                                                     |
| asChild        | `boolean \| undefined`                               |         | Use the provided child element as the default rendered element, combining their props and behavior. |

## Explorer