Checkbox

Use Checkbox when someone can choose an option independently of nearby controls. Pass description to clarify what the option means.

States

Use defaultSelected for an uncontrolled initial value, or pair isSelected with onChange when application state owns the selection. isIndeterminate communicates a mixed state, such as a parent option whose child options are only partly selected.

Size

Use size to change the checkbox control. It does not change the label typography. medium is the default. Use small in compact layouts and large where a larger control improves scanning.

Validation

Set isRequired to require the choice. Checkbox shows its validation message after validation fails. Pass errorMessage only for an error you already have, such as one from a form library or your server. A non-empty message marks the checkbox invalid. Read Validation for where messages come from and how to write them.

Labels with Text

Wrap a checkbox in block Text when its label needs a specific text size. The control follows the inherited line height. It keeps its fixed visual square centred on the first line when the label wraps. Outside Text, it uses the normal compact control size.

Accessibility

Pass a visible label as Checkbox children. Use aria-label only when surrounding content already names the control.

Disabled checkboxes cannot receive focus, and their value cannot change. Read-only checkboxes remain focusable, so someone who uses a keyboard or assistive technology can still perceive their state. Keyboard navigation shows a focus ring. Pointer focus does not.

Related components

Use the Checkbox primitive to arrange the clickable content, control, indicator, description, and error slots yourself.

API