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.
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
Checkboxif 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
Checkboxis based on a native<input type="checkbox">element and is accessible by default.- Always supply a
labelprop or anaria-labelattribute. An unlabeled checkbox is not announced correctly by screen readers. - The
labelelement is part of the clickable hit area, making it easier to activate for users with motor difficulties. - Indeterminate state: when
indeterminateis set, the nativeinput.indeterminateDOM property is set totrue, which causes browsers to exposearia-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:
Tabto focus,Spaceto toggle,Shift+Tabto 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 exposesaria-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.errorfor both the border and the helper text color. - Component token file — the
checkboxtoken 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.