DocsBlog
  • 0.25.3

  • light

    dark

    system

    Switch mode
  • Cerberus

    Acheron

    Elysium

Get Started
Components
Styling
Theming

Concepts

OverviewCompositionTesting

Layout

Aspect RatioBleedBoxCenterContainerDividerFlexFloatGridLink OverlayScrollableStackWrap

Components

AccordionAdmonitionAvatarButtonCarouselCheckboxClipboardCollapsibleComboboxConfirm ModalCTAModalDate PickerDialogFieldFieldsetFile UploaderIcon ButtonInputLoading StatesMenuNotificationsNumber InputPin InputProgressPrompt ModalRadioRatingSelectSplit ButtonSwitchTableTabsTagTextTextareaToggleTooltip

Utilities

Client OnlyDownload TriggerEnvironmentFeature FlagsFocus TrapForFormat ByteFormat NumberFormat Relative TimeFrameHighlightJSON Tree ViewLocaleLocal StoragePortalPresenceShowsplitPropsTheme

Checkbox

The Checkbox component allows users to select one or more options from a set.

  • npm
  • source
  • recipe
  • Ark
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.

Copy
checkbox group
import { Checkbox, CheckboxGroup, For } from '@cerberus/react'
export function CheckboxPreview() {
const items = [
{
id: 'terms',
label: 'I agree to the terms and conditions',
required: true,
},
{
id: 'legal',
label: 'I would like to receive marketing emails',
},
]
return (
<CheckboxGroup name="user_acceptance">
<For each={items}>
{(item) => (
<Checkbox
key={item.id}
ids={{ control: item.id }}
required={Boolean(item.required)}
>
{item.label}
</Checkbox>
)}
</For>
<Checkbox ids={{ control: 'mixed' }} checked="indeterminate">
The indeterminate state
</Checkbox>
</CheckboxGroup>
)
}

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.

Copy
checkbox group
'use client'
import { Checkbox, CheckboxGroup } from '@cerberus/react'
import { Box } from 'styled-system/jsx'
import { useState } from 'react'
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 IndeterminatePreview() {
const [values, setValues] = useState(initialValues)
const allChecked = values.every((value) => value.checked)
const indeterminate = values.some((value) => value.checked) && !allChecked
const items = values.map((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>
))
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>
{items}
</CheckboxGroup>
</Box>
)
}

Sizes

The Checkbox component supports different sizes. You can set the size prop to sm, or md.

Copy
checkbox sizes
import { Checkbox, CheckboxGroup } from '@cerberus/react'
function SizeDemo() {
return (
<CheckboxGroup name="size">
<Checkbox ids={{ control: 'small' }} size="sm">
Small
</Checkbox>
<Checkbox ids={{ control: 'medium' }} size="md">
Medium
</Checkbox>
</CheckboxGroup>
)
}

Primitives

You can utilize the primitive components or the css prop to customize the checkbox.

ComponentDescription
CheckboxRootThe context provider for the Checkbox parts
CheckboxLabelThe label of the checkbox
CheckboxControlThe input of the checkbox
CheckboxIndicatorThe indicator of the checkbox state
CheckboxGroupThe group container for multiple checkboxes
CheckboxHiddenInputThe native input for the checkbox
Copy
custom checkbox
import { CheckboxParts } from '@cerberus/react'
function CustomCheckbox() {
return (
<Box w="1/2">
<CheckboxParts.Root>
<CheckboxParts.Label>Custom Checkbox</CheckboxParts.Label>
<CheckboxParts.Control
css={{
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>
)
}

API

Props

The Checkbox component is an abstraction of the primitives and accepts the following props:

NameDefaultDescription
sizesmThis 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.

Note

It is best to only use the CheckboxParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

NameDescription
RootThe CheckboxRoot component which is the Provider for the family.
LabelThe CheckboxLabel component which displays the label and "required" notice.
ControlThe CheckboxControl component which is the visual field.
IndicatorThe CheckboxIndicator component which displays based on the checked state.
GroupThe CheckboxGroup component which creates a controls the spacing of a group.
HiddenInputThe CheckboxHiddenInput component which displays the native input.

On this page

  • Edit this page on Github
Cerberus Design System | Docs