Checkbox
Checkboxes let users select one or more items from a list, or turn an item on or off
- Use checkboxes (instead of switches or radio buttons) if multiple options can be selected from a list
- Label should be scannable
- Selected items are more prominent than unselected items
Example
Resources
| Name | Resource | Status |
|---|---|---|
| Figma | Design Kit (Figma) | Private |
On this page
Usage
Checkboxes visually group similar items effectively and take up less space than toggles.
Standard Checkbox
Alternate selection controls
Checkboxes, radio buttons, and toggles are the three main types of selection controls. They all help people make choices, like selecting options or switching settings on or off.
Use checkboxes to select multiple related options in a list.
Use radio buttons to select a single option in a list.
Use toggles to select standalone or more verbose options in a list, like settings.
On this page
import { Checkbox, CheckboxGroup, CheckboxParts } from '@cerberus/react'Usage
The Checkbox component is a controlled component that can be used to select one or more options from a set. It can be used in a group with other checkboxes to allow for multiple selections.
Indeterminate State
The Checkbox component supports the indeterminate state, which is useful for indicating that a group of checkboxes is in a mixed state. To enable this state, set the checked prop to indeterminate.
Sizes
The Checkbox component supports different sizes. You can set the size prop to sm, or md.
Primitives
You can utilize the primitive components to customize the checkbox.
| Component | Description |
|---|---|
| CheckboxRoot | The context provider for the Checkbox parts |
| CheckboxLabel | The label of the checkbox |
| CheckboxControl | The input of the checkbox |
| CheckboxIndicator | The indicator of the checkbox state |
| CheckboxGroup | The group container for multiple checkboxes |
| CheckboxHiddenInput | The native input for the checkbox |
API
Props
The Checkbox component is an abstraction of the primitives and accepts the following props:
| Name | Default | Description |
|---|---|---|
| size | sm | This size of the Checkbox. |
The Checkbox component also accepts all the props of the CheckboxRoot primitive props
Parts
The CheckboxParts API is an Object containing the full family of components.
| Name | Description |
|---|---|
| Root | The CheckboxRoot component which is the Provider for the family. |
| Label | The CheckboxLabel component which displays the label and "required" notice. |
| Control | The CheckboxControl component which is the visual field. |
| Indicator | The CheckboxIndicator component which displays based on the checked state. |
| Group | The CheckboxGroup component which creates a controls the spacing of a group. |
| HiddenInput | The CheckboxHiddenInput component which displays the native input. |
On this page
Use Cases
- Users should be able to:
- Navigate to a checkbox with assistive technology
- Toggle the checkbox on and off
- Get appropriate feedback based on input type documented under Interaction & style
Interaction & Style
The parent checkbox has three states: selected, unselected, and mixed.
Checkboxes can be selected or unselected regardless of the state of the other checkboxes in a group.
If some, but not all, child checkboxes are checked, the parent checkbox becomes mixed. Selecting an mixed parent checkbox will check all of its child checkboxes.
Keyboard Navigation
| Keys | Actions |
|---|---|
| Tab | To move to the next element in a group |
| Space | Toggles a focused checkbox between selected and unselected |
Labeling Elements
If the UI text is correctly linked to the checkbox, assistive tech (such as a screen reader) will read the UI text followed by the component's role.
The accessibility label for an individual checkbox is typically the same as its adjacent text label.
On this page