Checkbox
Native checkbox. Children are the visible label. There is no indeterminate state.
Controlled when checked is defined. Uncontrolled when you pass defaultChecked or omit both. useControlledState does not fire onCheckedChange. The component does.
<Checkbox defaultChecked>Product updates</Checkbox>
<Checkbox checked={accepted} onCheckedChange={setAccepted} invalid={invalid} aria-describedby={errorId}>
I accept the terms
</Checkbox>
Accept the terms to continue.
Do not put Checkbox inside Field.Root. The shell is for text and chip inputs. Wire aria-describedby on the checkbox when a Description or ErrorMessage sits under it.
For a permanent exclusive choice, use Radio. For an overlay list, use OptionList.
When to use
When: Independent on/off that stays on the page. Children = visible label.
When not: Exclusive one-of → Radio. Instant setting toggle look → Switch. Overlay multi-select → OptionList selectionMode="multiple". Inside Field.Root.
Props
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| children | React.ReactNode | yes | — | Visible label. Clicking the text toggles the input. |
| checked | boolean | no | — | Controlled checked state. Defined means controlled. |
| defaultChecked | boolean | no | — | Initial checked state when uncontrolled. |
| onCheckedChange | (checked: boolean) => void | no | — | Fires after the checked state changes. |
| disabled | boolean | no | — | Disables the input. |
| invalid | boolean | no | — | Marks the control invalid and sets aria-invalid. |
| name | string | no | — | Native input name. |
| value | string | no | — | Native input value. |
| className | string | no | — | Optional class on the wrapping label. |