Checkbox

• Let people pick any number of options from a list, such as the columns to export.
• Select or clear a whole group in one click with a parent checkbox that shows a dash when only some are checked.
• Collect an opt-in that only takes effect when a form is submitted, such as "Include totals".

• A setting that applies the moment it changes: use a Switch.
• Exactly one choice from a few: use a Radio Group or Segmented.
• Toggling formatting in a toolbar: use a Toggle Group.

Group with a parent

Wrap checkboxes in CheckboxGroup to share one value array. A parent checkbox checks or clears them all and shows the dash when some are checked; pass every child's value as allValues.

const columns = ["invoice", "customer", "amount", "status"];const [value, setValue] = useState(["invoice", "amount"]);<CheckboxGroup aria-label="Columns" value={value} onValueChange={setValue} allValues={columns}>  <Checkbox parent>All columns</Checkbox>  <Checkbox value="invoice">Invoice number</Checkbox>  <Checkbox value="customer">Customer</Checkbox>  <Checkbox value="amount">Amount</Checkbox>  <Checkbox value="status">Status</Checkbox></CheckboxGroup>

Disabled, with the reason

Say why an option is unavailable in description, so people know what would unlock it.

<Checkbox disabled description="Available on the Business plan.">  Schedule a weekly export</Checkbox>

Bare box

Leave out children in a table row or another layout that already shows the label, and name it with aria-label.

<Checkbox aria-label="Select invoice INV-2041" checked={selected} onCheckedChange={setSelected} />

Checkbox

CheckboxGroup

• The root has role="checkbox" and aria-checked, which reads "mixed" when indeterminate. A hidden input submits it with forms and works with Field validation.
• With children, the label names the checkbox through aria-labelledby, and description describes it through aria-describedby. Without children, pass aria-label.
• The focus ring draws around the whole row, label included.
• A labelled row is 32px tall and toggles anywhere you press. A bare box is 16px, so give it a larger row or cell to press in on touch screens.

The fill and border tint in over 150ms on the standard curve. The check draws itself in 200ms on the enter curve and retracts in 100ms on the exit curve as it fades. The indeterminate dash is the same stroke straightened, so check and dash morph into each other on the snappy spring instead of cross-fading. The box presses to 0.9 in 100ms and springs back on the snappy spring; disabled and read-only boxes don't press. Reduced motion: the mark appears and disappears with a 100ms fade, and the box doesn't press.

Pick Checkbox for options that take effect on submit and for multi-select lists; pick Switch when the change applies at once. For a "Select all", use CheckboxGroup with a parent checkbox and allValues; don't compute the indeterminate state yourself.

Don't wrap it in a <label> or put a Label next to it: pass the label as children and the helper text as description, and the row handles naming and the click target. Don't animate the check yourself.

A long label wraps under itself, and the box stays on the label's first line. Descriptions wrap with text-pretty.

• Switch: a setting that applies the moment it flips.
• Radio Group: exactly one choice from a list.
• Field: adds validation messages around a control.