Checkbox
Capture an independent checked, unchecked, or mixed choice.
I agree to the privacy policy and terms of service.
Anatomy#
Usage#
Use Checkbox for an independent boolean or mapped choice that can be selected alongside other choices. Use Switch when the control represents an immediate on/off setting. Use CheckboxGroup when several choices submit as one array.
State and form values#
Use checked with onCheckedChange for controlled state, or defaultChecked for an initial value.
Pass checked="indeterminate" from aggregate selection state; it shows the mixed presentation
without adding a third submitted value.
trueValue and falseValue map the checked state to domain values. onCheckedChange receives them,
and a bound form.Field stores them. Native form submission uses value while checked. Without
value, it submits a string or number trueValue, or 'on' otherwise. An unchecked or
indeterminate checkbox contributes no entry. onCheckedChange fires only for user toggles, never
while disabled or readOnly, and toggling from 'indeterminate' checks the box.
Label, description, and layout#
label and description render beside the control and link to it for assistive technology. Set
variant="card" to draw a bordered card whose whole surface toggles the checkbox, except for
interactive content inside it. indicatorPosition places the control at the leading (default) or
trailing edge, or hides it visually with hidden. size accepts sm, md (default), or lg.
Read-only and disabled#
disabled removes the control from normal interaction and native form submission. readOnly
preserves the value and focusability while preventing changes.
Examples#
Complete a deployment checklist#
Drive a parent checkbox from child task state. Pass checked="indeterminate" when some but not all
tasks are done. checkedIcon and indeterminateIcon replace the default marks.
Store telemetry as domain values#
Map checked and unchecked to application strings with trueValue and falseValue. Callbacks and
schema fields then receive those strings instead of booleans.
Save cookie consent for Consent Mode#
Consent Mode reads each consent type as 'granted' or 'denied'. Set trueValue="granted" and
falseValue="denied" inside form.Field. The schema validates and submits those strings directly,
so the output goes straight to gtag('consent', 'update', ...) without a boolean mapping step.
Require terms on submit#
Bind the checkbox to form.Field and reject false in the schema so submit cannot proceed until
the terms are accepted.
Subscribe to product updates#
Own checked in the page when nearby copy must reflect the same boolean.
Lock a policy versus show a read-only copy#
disabled removes the control from interaction and native submit. readOnly stays focusable and
submits, but rejects changes.
API Reference#
Attributes#
data-checkeddata-disableddata-indeterminatedata-invaliddata-readonlydata-requireddata-uncheckedProps#
Props for the Checkbox component. Renders a <div> element by default.