Checkbox
Accessible React checkbox with label, helper text, error state, indeterminate mode, and three sizes. Built on Radix, wired for forms, and RTL ready.
Checkbox toggles a single option. It supports label, helperText, errorMessage, an indeterminate state, and three sizes.
When to use
Use Checkbox for an option the user opts into and submits later, such as a consent statement or selecting several items in a list. Use Switch when the change applies immediately. Use the indeterminate state for a parent checkbox that reflects a partially selected group.
For a single choice from a set, use RadioGroup.
Examples
Props
Props declared by Checkbox. Native attributes of the underlying element pass through.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "md" | "xs" | ||
variant | "primary" | "neutral" | ||
label | react.ReactNode | Visible label, sits beside the box, associated via htmlFor/id. | |
helperText | react.ReactNode | Hint shown below the row. Hidden while an error message is showing. | |
errorMessage | react.ReactNode | Message shown below the row when error is true. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. | |
readOnly | boolean | Locks the value: shows state but can't be toggled; stays focusable, sets aria-readonly. | |
checked | CheckedState | ||
defaultChecked | CheckedState | ||
required | boolean | ||
onCheckedChange | (checked: CheckedState) => void | ||
asChild | boolean |
Accessibility
Checkbox is built on Radix and exposes the checkbox role with checked, unchecked, and mixed states. The label is associated so clicking it toggles the box, and helper text and errors are announced. Space toggles the state.
Keep consent text short and put the full terms behind a Link so the label stays readable.