Checkbox
Use Checkbox for a choice that takes effect when a form is submitted: agree to the terms, or, with CheckboxGroup, pick any number of options from a short list. For a setting that applies right away, use Switch; to pick several items from a long list, use Select with multiple.
Checkbox is a native input type="checkbox" with a drawn box, inside a label with its text, so forms, labels, keyboard and screen readers work as they do for any checkbox. CheckboxGroup holds the checked values of the checkboxes inside it.
#Demos
#Basic
Give the label as children or label. Without visible text, name the checkbox with aria-label.
#Size
#Controlled
checked with onCheckedChange puts the state in your hands.
#Custom values
checkedValue and uncheckedValue replace true and false in checked and onCheckedChange.
#Indeterminate
indeterminate shows a line instead of the check, for a “select all” box whose items are only partly checked. Screen readers announce it as mixed.
#Group
Each Checkbox inside a CheckboxGroup takes a value, and the group’s value lists the checked ones. With max, the unchecked boxes disable once that many are checked; with min, the checked ones disable once only that many are left. name submits every checked value with a form.
#Disabled
A disabled checkbox keeps its state visible. disabled on a group disables every checkbox in it.
#Checkbox Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
checked | boolean | string | number | undefined | Checked state when controlled: checked while it equals checkedValue. | Unreleased |
defaultChecked | boolean | string | number | uncheckedValue | Initial state when uncontrolled. | Unreleased |
checkedValue | boolean | string | number | true | The value checked takes when checked. | Unreleased |
uncheckedValue | boolean | string | number | false | The value checked takes when unchecked. | Unreleased |
indeterminate | boolean | false | Shows a line instead of the check. | Unreleased |
disabled | boolean | false | Disables the checkbox. | Unreleased |
focusable | boolean | true | false takes it out of the tab order and keeps clicks from focusing it. | Unreleased |
label | ReactNode | undefined | The label; wins over children. | Unreleased |
size | small | medium | large | medium | Box and text size. | Unreleased |
value | string | number | undefined | The checkbox’s value in a CheckboxGroup; also the native input’s value. | Unreleased |
onCheckedChange | (checked, event) => void | undefined | Called with the new checkedValue or uncheckedValue. Not called inside a group. | Unreleased |
className and style go to the label; ref and every other native attribute (id, name, required, aria-*, onFocus, …) go to the native input.
#CheckboxGroup Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
value | (string | number)[] | null | undefined | Checked values when controlled. | Unreleased |
defaultValue | (string | number)[] | null | null | Initially checked values when uncontrolled. | Unreleased |
disabled | boolean | false | Disables every checkbox in the group. | Unreleased |
max | number | undefined | At most this many can be checked. | Unreleased |
min | number | undefined | At least this many stay checked. | Unreleased |
name | string | undefined | The native name of every checkbox inside. | Unreleased |
size | small | medium | large | undefined | Size of every checkbox that doesn’t set its own. | Unreleased |
onUpdateValue | (value, meta: { actionType: "check" | "uncheck", value }) => void | undefined | Called with the new checked values and what changed. | Unreleased |
The group renders a div with role="group" and lays nothing out: place the checkboxes in any layout, and name the group with aria-label or aria-labelledby. To render a list of options, map them to Checkboxes.