---
title: Checkbox
description: Select independent options with checked and indeterminate states.
---

import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';

import CheckboxReference from '/snippets/ui/generated/input/checkbox.mdx';

Use `Checkbox` when each option can be selected independently. For a mutually exclusive choice, use [RadioGroup](/ui/primitives/input/radio-group).

<StoryEmbed
  storyId="ui-input-checkbox-checkbox--default"
  title="Checkbox example"
  height={240}
/>

## Uncontrolled state

Use `defaultChecked` to set the initial checked state. The checkbox owns subsequent changes.

```tsx
import { Checkbox } from 'twenty-ui/primitives/input';

export const EmailPreference = () => (
  <label>
    <Checkbox name="updates" value="email" defaultChecked />
    Receive product updates
  </label>
);
```

A checked, named checkbox contributes its value to a form. Set `uncheckedValue` if the form should also submit a value when it is unchecked.

## Controlled state

Pass `checked` and update it with `onCheckedChange` to own the same preference in React state. The callback receives the next boolean and event details.

```tsx
import { useState } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';

export const EmailPreference = () => {
  const [checked, setChecked] = useState(true);

  return (
    <label>
      <Checkbox
        name="updates"
        value="email"
        checked={checked}
        onCheckedChange={setChecked}
      />
      Receive product updates
    </label>
  );
};
```

## Indeterminate state

An indeterminate checkbox represents a partial selection. Derive it from the child options independently of the checkbox's checked state.

```tsx
import { useState } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';

export const ColumnSelection = () => {
  const [showEmail, setShowEmail] = useState(true);
  const [showPhone, setShowPhone] = useState(false);

  return (
    <fieldset>
      <legend>Visible columns</legend>
      <label>
        <Checkbox
          checked={showEmail && showPhone}
          indeterminate={showEmail !== showPhone}
          onCheckedChange={(checked) => {
            setShowEmail(checked);
            setShowPhone(checked);
          }}
        />
        All columns
      </label>
      <label>
        <Checkbox checked={showEmail} onCheckedChange={setShowEmail} />
        Email
      </label>
      <label>
        <Checkbox checked={showPhone} onCheckedChange={setShowPhone} />
        Phone
      </label>
    </fieldset>
  );
};
```

## Appearance and interaction

| Prop      | Values                         | Default  |
| --------- | ------------------------------ | -------- |
| `size`    | `sm`, `md`                     | `sm`     |
| `variant` | `solid`, `outline`, `soft`     | `solid`  |
| `shape`   | `square`, `round`              | `square` |
| `color`   | `accent`, `success`, `warning` | `accent` |

Tab focuses the checkbox and Space toggles it. Clicking its label also toggles it. Use `disabled` to prevent interaction, or `readOnly` when the value should remain unchanged while the control stays focusable. Keep meaning in the label rather than communicating it through color alone.

## Props

The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.

<CheckboxReference />