> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkbox Component: Binary Form Input for React Apps

> The Clementine DS Checkbox for binary on/off selections — supports indeterminate state, error display, and accessible keyboard interaction.

`Checkbox` is Clementine DS's binary form input. It wraps Mantine's `Checkbox` component and re-exports it with Clementine token bindings applied through `ClementineDSProvider`. Import from `@clementine-ds/ui`, not from `@mantine/core` directly.

> [!WARNING]
>
> **Draft** — `Checkbox` is a Draft component. It renders correctly and keyboard behavior is functional, but ARIA verification for `aria-checked="mixed"` (indeterminate) is outstanding. Component token values are pending. Storybook stories for indeterminate and error states are missing.

Use `Checkbox` for non-exclusive selections, opt-in/opt-out toggles inside forms, and parent/child multi-select trees where the parent needs an indeterminate state. For mutually exclusive single-choice groups use `Radio`. For a persistent settings toggle outside a form use `Switch`.

***

## When to use

* The user must make a binary decision: accept terms, opt into a feature, enable a flag.
* Multiple non-exclusive items can be selected simultaneously (a checklist, a filter panel, a permission list).
* You need an indeterminate state for a "select all" checkbox that sits above a list of checkboxes where only some items are checked.
* The input lives inside a form that submits with `FormData`.

## When not to use

* **Mutually exclusive choices** — use `Radio`. A group of checkboxes implies each item is independent, which is wrong for "pick exactly one" scenarios.
* **On/off settings outside a form** — use `Switch`. A checkbox requires an explicit form submit to take effect; a switch communicates immediate action.
* **Visual-only state indicator** — use a read-only display element rather than a `Checkbox` if you need a checked/unchecked icon without any keyboard interaction or form submission behavior.

***

## Usage

```tsx theme={null}
import { Checkbox } from '@clementine-ds/ui';

// Basic with label
<Checkbox label="I agree to the terms and conditions" />

// With description
<Checkbox
  label="Receive marketing emails"
  description="We send roughly one email per month. Unsubscribe any time."
/>

// Required inside a form
<Checkbox
  label="I confirm this information is accurate"
  required
/>

// Error state with message
<Checkbox
  label="Accept terms"
  error="You must accept the terms to continue."
/>

// Indeterminate — used on a "select all" parent
<Checkbox
  label="Select all"
  checked={allChecked}
  indeterminate={someChecked && !allChecked}
  onChange={() => setAllChecked((c) => !c)}
/>

// Disabled
<Checkbox label="Legacy feature (unavailable)" disabled />

// Disabled and pre-checked
<Checkbox label="Included by default" checked disabled onChange={() => {}} />

// Label on the left side
<Checkbox label="Dark mode" labelPosition="left" />
```

### Controlled usage

```tsx theme={null}
import { useState } from 'react';
import { Checkbox } from '@clementine-ds/ui';

function TermsCheckbox() {
  const [accepted, setAccepted] = useState(false);

  return (
    <Checkbox
      label="I accept the terms and conditions"
      checked={accepted}
      onChange={(event) => setAccepted(event.currentTarget.checked)}
    />
  );
}
```

### Indeterminate "select all" pattern

```tsx theme={null}
import { useState } from 'react';
import { Checkbox, Stack } from '@clementine-ds/ui';

const ITEMS = ['Email notifications', 'SMS notifications', 'Push notifications'];

function NotificationPreferences() {
  const [checked, setChecked] = useState<boolean[]>(ITEMS.map(() => false));

  const allChecked = checked.every(Boolean);
  const indeterminate = checked.some(Boolean) && !allChecked;

  return (
    <Stack gap="xs">
      <Checkbox
        label="All notifications"
        checked={allChecked}
        indeterminate={indeterminate}
        onChange={() => setChecked(ITEMS.map(() => !allChecked))}
      />
      {ITEMS.map((item, index) => (
        <Checkbox
          key={item}
          label={item}
          checked={checked[index]}
          onChange={(event) =>
            setChecked((prev) =>
              prev.map((v, i) => (i === index ? event.currentTarget.checked : v))
            )
          }
          ml={28}
        />
      ))}
    </Stack>
  );
}
```

### Uncontrolled usage with FormData

```tsx theme={null}
import { Checkbox } from '@clementine-ds/ui';

function ConsentForm() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        console.log('Accepted:', !!formData.get('terms'));
      }}
    >
      <Checkbox label="Accept terms and conditions" name="terms" defaultChecked />
      <button type="submit">Submit</button>
    </form>
  );
}
```

***

## Props

`CheckboxProps` extends Mantine's `CheckboxProps` directly. The table below covers the props you'll use most often.

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `React.ReactNode` | — | The visible text label. Also the clickable hit area that toggles the checkbox. Always provide `label` or `aria-label`. |
| `description` | `React.ReactNode` | — | Optional helper text rendered below the label. |
| `error` | `React.ReactNode` | — | Error message rendered below the label. Triggers error border and text color. Pass `true` for error styling without a message. |
| `checked` | `boolean` | — | Controlled checked state. |
| `defaultChecked` | `boolean` | — | Uncontrolled initial checked state. |
| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | — | Called when the checkbox is toggled. Receives the native change event; read `event.currentTarget.checked` for the new state. |
| `indeterminate` | `boolean` | — | Puts the checkbox into the indeterminate (mixed) state. When set, `checked` is ignored for styling — the checkbox always renders with checked styles and a dash icon. |
| `disabled` | `boolean` | — | Sets the `disabled` attribute and applies disabled visual styles. |
| `required` | `boolean` | — | Adds the `required` attribute to the input. |
| `id` | `string` | — | Custom `id` for the input element. Used as `htmlFor` on the label. A random `id` is generated if not provided. |
| `name` | `string` | — | Native `name` attribute. Required for uncontrolled forms with `FormData`. |
| `value` | `string` | — | Value submitted with a form. Also used by `Checkbox.Group` to track selections. |
| `labelPosition` | `"left" \| "right"` | `"right"` | Controls whether the label appears to the left or right of the box. |
| `color` | `MantineColor` | — | Background color of the checkbox in the checked state. Accepts theme color keys or any valid CSS color. |
| `iconColor` | `MantineColor` | — | Color of the checkmark icon. Defaults to a value based on `theme.autoContrast`. |
| `autoContrast` | `boolean` | — | Automatically adjusts the icon color to ensure sufficient contrast with the `color` background. Only works with the `filled` variant. |
| `icon` | `CheckboxIconComponent` | — | Custom icon component for the checked and indeterminate states. |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"sm"` | Controls the size of the checkbox box and label font. |
| `radius` | `MantineRadius \| number` | — | Sets the `border-radius` of the box. Accepts theme radius keys or a raw CSS value. |
| `variant` | `"filled" \| "outline"` | `"filled"` | Visual style of the checkbox box. |
| `withErrorStyles` | `boolean` | — | Set to `false` to suppress error styles while still displaying the error message. |
| `rootRef` | `Ref<HTMLDivElement>` | — | Ref forwarded to the root wrapper element (useful for attaching tooltips to the full component). |
| `wrapperProps` | `React.ComponentProps<"div">` | — | Extra props spread onto the root wrapper element. |

***

## Interaction states

| State | Trigger | Visual change |
| - | - | - |
| **Default (unchecked)** | Idle, unchecked | `checkbox.bg.unchecked` background, `checkbox.border.default` border |
| **Hover** | Mouse over checkbox or label | `checkbox.border.focus` border tint |
| **Focus** | Keyboard focus on the checkbox input | `checkbox.border.focus` border + `checkbox.ring` focus ring |
| **Checked** | `checked={true}` | `checkbox.bg.checked` background, checkmark icon in `checkbox.check` color |
| **Indeterminate** | `indeterminate={true}` | `checkbox.bg.indeterminate` background, dash icon instead of checkmark |
| **Disabled** | `disabled={true}` | `checkbox.bg.disabled` background, pointer events removed |
| **Error** | `error` prop is set | `checkbox.border.error` border, error message in `checkbox.fg.error` color |

***

## Token contract

| Token | Semantic alias |
| - | - |
| `checkbox.bg.unchecked` | `surface.elevated` |
| `checkbox.bg.checked` | `interactive.primary` |
| `checkbox.bg.indeterminate` | `interactive.primary` |
| `checkbox.bg.disabled` | `surface.subtle` |
| `checkbox.check` | `text.on-primary` |
| `checkbox.border.default` | `border.strong` |
| `checkbox.border.focus` | `border.focus` |
| `checkbox.border.error` | `feedback.error` |
| `checkbox.fg.label` | `text.primary` |
| `checkbox.fg.description` | `text.secondary` |
| `checkbox.fg.error` | `feedback.error` |
| `checkbox.radius` | `radius.checkbox` |

***

## Accessibility

* `Checkbox` is based on a native `<input type="checkbox">` element and is accessible by default.
* Always supply a `label` prop or an `aria-label` attribute. An unlabeled checkbox is not announced correctly by screen readers.
* The `label` element is part of the clickable hit area, making it easier to activate for users with motor difficulties.
* **Indeterminate state**: when `indeterminate` is set, the native `input.indeterminate` DOM property is set to `true`, which causes browsers to expose `aria-checked="mixed"` to assistive technology. Verify this in your target browser before shipping. See the draft status note below.
* On error, the error message is associated with the input via `aria-describedby`. Verify this wiring is in place.
* Keyboard interaction: `Tab` to focus, `Space` to toggle, `Shift+Tab` to move backwards.
* Use `rootRef` (not the default ref) to attach tooltips to the entire component including the label. If you only ref the input, the tooltip attaches to the box alone.

***

## Draft status

`Checkbox` carries a **Draft** status as of `clementine-ds@HEAD (2026-06-08)`. The following items are still open:

* **`aria-checked="mixed"` verification** — it needs to be confirmed that Mantine's default ARIA output correctly exposes `aria-checked="mixed"` for the indeterminate state in all supported browsers and screen readers.
* **Error state token binding** — it needs to be confirmed that the error state binds `feedback.error` for both the border and the helper text color.
* **Component token file** — the `checkbox` token file is pending. The token names in this document match the spec but have not been validated against the live rendered output.
* Storybook stories are missing for: indeterminate, error.

Do not build production-critical token overrides against this component until these items are resolved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.