The Checkbox component allows users to select one or more options from a set.
import { Checkbox, CheckboxGroup } from '@cerberus/react'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.
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.
The Checkbox component supports different sizes. You can set the size prop to sm, or md.
You can customize the Checkbox any way you like with style props and data-selectors.
The layers of the Checkbox which can be used to create a fully custom solution.
| 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 |
The primitives additionally use the following data attributes for custom styling:
| Name | Value | Description |
|---|---|---|
data-scope | checkbox | The scope of the components. |
data-part | root | The root layer of the scope. |
data-part | label | The label layer of the scope. |
data-part | control | The control layer of the scope. |
data-part | indicator | The indicator layer of the scope. |
data-part | group | The group layer of the scope. |
data-active | Present when active or pressed | |
data-focus | Present when focused | |
data-focus-visible | Present when focused with keyboard | |
data-readonly | Present when read-only | |
data-hover | Present when hovered | |
data-disabled | Present when disabled | |
data-state | "indeterminate" | "checked" | "unchecked" | |
data-invalid | Present when invalid | |
data-required | Present when required |
The Checkbox component is an abstraction of the primitives and accepts the following props:
| Prop | Type | Required | Description |
|---|---|---|---|
asChild | boolean | No | Use the provided child element as the default rendered element, combining their props and behavior. |
size | sm | No | This size of the Checkbox. |
checked | CheckedState | No | The controlled checked state of the checkbox |
defaultChecked | CheckedState | No | The initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox. |
disabled | boolean | No | Whether the checkbox is disabled |
form | string | No | The id of the form that the checkbox belongs to. |
id | string | No | The unique identifier of the machine. |
ids | Partial<{ root: string; hiddenInput: string; control: string; label: string }> | No | The ids of the elements in the checkbox. Useful for composition. |
invalid | boolean | No | Whether the checkbox is invalid |
name | string | No | The name of the input field in a checkbox. |
| Useful for form submission. | |||
onCheckedChange | (details: CheckedChangeDetails) => void | No | The callback invoked when the checked state changes. |
readOnly | boolean | No | Whether the checkbox is read-only |
required | boolean | No | Whether the checkbox is required |
value | string | No | The value of checkbox input. Useful for form submission. |
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 client'
import { Box } from '@/styled-system/jsx'
import { Checkbox, CheckboxGroup, For } from '@cerberus/react'
const items = [
{
id: 'terms',
label: 'I agree to the terms and conditions',
required: true,
},
{
id: 'legal',
label: 'I would like to receive marketing emails',
},
]
export function BasicDemo() {
return (
<Box w="1/2">
<CheckboxGroup name="user_acceptance">
<For each={items}>
{(item) => (
<Checkbox
key={item.id}
ids={{ control: item.id }}
required={item?.required}
>
{item.label}
</Checkbox>
)}
</For>
<Checkbox ids={{ control: 'mixed' }} checked="indeterminate">
The indeterminate state
</Checkbox>
</CheckboxGroup>
</Box>
)
}
'use client'
import { Checkbox, CheckboxGroup, For } from '@cerberus/react'
import { createComputed, useSignal } from '@cerberus/signals'
import { Box } from 'styled-system/jsx'
const initialValues = [
{ label: 'Monday', checked: false, value: 'monday' },
{ label: 'Tuesday', checked: false, value: 'tuesday' },
{ label: 'Wednesday', checked: false, value: 'wednesday' },
{ label: 'Thursday', checked: false, value: 'thursday' },
]
export function IndeterminateDemo() {
const [values, setValues] = useSignal(initialValues)
const allChecked = createComputed(() => values.every((value) => value.checked))
const indeterminate = createComputed(
() => values.some((value) => value.checked) && !allChecked(),
)
return (
<Box w="1/2">
<CheckboxGroup name="days">
<Checkbox
checked={indeterminate() ? 'indeterminate' : allChecked()}
onCheckedChange={(e) => {
setValues((current) =>
current.map((value) => ({ ...value, checked: !!e.checked })),
)
}}
>
Weekdays
</Checkbox>
<For each={values}>
{(item, index) => (
<Checkbox
key={item.value}
checked={item.checked}
onCheckedChange={(e) => {
setValues((current) => {
const newValues = [...current]
newValues[index] = { ...newValues[index], checked: !!e.checked }
return newValues
})
}}
>
{item.label}
</Checkbox>
)}
</For>
</CheckboxGroup>
</Box>
)
}
'use client'
import { Box } from '@/styled-system/jsx'
import { Checkbox, CheckboxGroup } from '@cerberus/react'
export function SizeDemo() {
return (
<Box w="1/2">
<CheckboxGroup name="size">
<Checkbox ids={{ control: 'small' }} size="sm">
Small
</Checkbox>
<Checkbox ids={{ control: 'medium' }} size="md">
Medium
</Checkbox>
</CheckboxGroup>
</Box>
)
}
'use client'
import { Box } from '@/styled-system/jsx'
import { ArrowDownRight } from '@carbon/icons-react'
import { CheckboxParts } from '@cerberus/react'
export function CustomDemo() {
return (
<Box w="1/2">
<CheckboxParts.Root>
<CheckboxParts.Label>Custom Checkbox</CheckboxParts.Label>
<CheckboxParts.Control
bgColor="black"
border="4px solid"
borderColor="danger.border.initial"
h={8}
rounded="none"
transform="skewX(-10deg)"
w={8}
_checked={{
bgColor: 'info.bg.initial',
}}
>
<CheckboxParts.Indicator>
<ArrowDownRight />
</CheckboxParts.Indicator>
</CheckboxParts.Control>
<CheckboxParts.HiddenInput />
</CheckboxParts.Root>
</Box>
)
}