Checkbox
A form control that toggles between checked and not checked, with an indeterminate state. Pair it with Field to connect its label, description, and errors in a form.
When to use
- Turn one or more independent options on or off in a form.
- Show a partial selection with the indeterminate state, such as a select-all box.
- Prefer
Switchwhen one setting turns on or off and needs no indeterminate state. - Prefer
RadioGroupwhen the user picks exactly one option from a set. - Prefer
Choicewhen the checkbox needs a title and a description beside it.
Without a Field
Render the control on its own, with a Label as its caption:
Multi-line label with description
For a checkbox with an emphasized title and a supplementary description beneath it, compose it inside Choice: drop the Checkbox into Choice.Indicator and pair Choice.Label (a real <label>, so clicking it toggles the box) with an optional Choice.Description. The description forwards its click to that label, so the whole text block toggles the box. The box aligns to the leading of the title's first line, and the description associates via aria-describedby.
Inside a Field
Wrap that same Choice in a Field.Item / Field.Control to bind a form name and pick up validation. The field's id / name / aria-* flow onto the checkbox, and the Field.Description (or a Field.Errors) is merged into the control's aria-describedby alongside the Choice.Description (no duplicate ids, no manual wiring):
For the fully-clickable list-row variant (and the full API), see the Choice docs.
With TanStack Form
Use @tanstack/react-form with zod to keep the checkbox controlled and render errors through Field.Errors.
Select-all helper
selectAllChecked resolves the tri-state checked value for a "select all" checkbox from the current selection counts: true when everything is selected, "indeterminate" when only some is, and false when nothing is. Use it to keep the header checkbox of a multi-select list correct without hand-rolling the tri-state branch. It pairs directly with a DataTable row-selection column:
Returns boolean | "indeterminate" (a CheckedState), ready to pass straight to Checkbox's checked prop. allSelected takes precedence, so it wins even if a caller also reports someSelected.
API Reference
Checkbox
All props from input[type="checkbox"], plus:
For a checkbox with a titled, multi-line label and a description, see Choice.