Forms
Checkbox
Checkbox is a native checkbox for independent or multi-select choices, including indeterminate group states.
Value (Unchecked/Checked/Indeterminate) × State — 12 variants
betaReact AvailableFigma AvailableDocs Partial
- React last updated
- 2026-07-13
- Documentation last updated
- 2026-06-01
- Accessibility target
- WCAG 2.2 AA (target)
- Version
- 0.2.0-beta
Known open questions
- Figma does not define a separate Checkbox size variant — single control size implemented.
- Checkbox controls intentionally ignore decorative Gradient/Glass surfaces.
Live preview
Native checkbox semantics with inline label. Checkbox affordance is preserved in every shape mode.
Unchecked / Checked / Indeterminate / Disabled
Error composition
Invalid state with FormField
Select at least one permission.
Purpose
Binary or tri-state selection within a group of independent options (not mutually exclusive).
Anatomy
Checkbox = native input[type=checkbox] + inline label text.
Variants and states
unchecked · checked · indeterminate · disabled · error
When to use
"Select any that apply" scenarios, agreement/consent checkboxes, or a single standalone toggle.
When not to use
Mutually exclusive single-choice (use Radio). A setting that takes effect immediately (use Switch).
Accessibility
Renders as a real <input type="checkbox"> with the label programmatically associated. Indeterminate must be set via the DOM property.
Keyboard behavior
Space toggles when focused. Standard tab order to the native input.
Common mistakes
Building the label as a separate, unassociated text element next to the box.
Properties
Value × State as variants. Label (text).
When should a Switch be used instead of a Checkbox?
Use Checkbox for form selections and consent that submit with a form. Use Switch for settings that apply immediately without a separate submit action.
Tokens used
semantic/surface/defaultsemantic/border/defaultsemantic/action/primarysemantic/focus-ring
Component API
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | — | Visible label associated with the native checkbox. |
| checked | boolean | — | Controlled checked state. |
| defaultChecked | boolean | — | Uncontrolled initial checked state. |
| indeterminate | boolean | false | Sets native indeterminate property. |
| disabled | boolean | false | Native disabled state. |
| aria-invalid | boolean | — | Error state when composed with FormField validation. |
React example
Copy React example
import { Checkbox } from "@/components/ui/Checkbox";
export function Example() {
return <Checkbox label="Email me product updates" defaultChecked />;
}