Skip to main content
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.
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

Controlled usage

Indeterminate “select all” pattern

Uncontrolled usage with FormData


Props

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

Interaction states


Token contract


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.