Checkbox
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.