Skip to main content

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 Switch when one setting turns on or off and needs no indeterminate state.
  • Prefer RadioGroup when the user picks exactly one option from a set.
  • Prefer Choice when 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.

OptionTypeDescription
allSelectedbooleanWhether every selectable item is currently selected.
someSelectedbooleanWhether some (but not necessarily all) items are selected.

API Reference

Checkbox

All props from input[type="checkbox"], plus:

PropTypeDefaultDescription
checked?boolean | "indeterminate"Whether the checkbox is checked or not. Setting this to "indeterminate" will show the indeterminate state. This is useful for parent-child relationships, but requires manual, controlled state.
defaultChecked?boolean | "indeterminate"The checked state of the checkbox when it is initially rendered. Use when you do not need to control its checked state.
readOnly?booleanfalseBlocks the toggle and sets aria-readonly. The native readonly attribute is inert on a checkbox, so mantle guards the click itself.
validation?"error" | "success" | "warning" | false | () => "error" | "success" | "warning" | falseUse the validation prop to show a specific validation status. This will change the border and outline of the checkbox. The false type is useful with short-circuiting logic. Setting validation to "error" also sets aria-invalid.

For a checkbox with a titled, multi-line label and a description, see Choice.