Checkbox
A controlled round multi-select control that toggles one item without committing an entire form.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/primitives/Checkbox/Checkbox.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A controlled round multi-select control that toggles one item without committing an entire form.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { Checkbox } from '@cloakedinc/design-system';CheckboxCheckboxProps
packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx:31
| Prop | Type | Presence | Notes |
|---|---|---|---|
checked | boolean | Required | Current state, exposed as `aria-checked`. |
onChange | ((checked: boolean) => void) | undefined | Optional | Called with the next checked value when pressed. |
disabled | boolean | undefined | Optional | Blocks the press and dims the chip. |
ariaLabel | string | undefined | Optional | Accessible label when no visible label is associated with the checkbox. |
className | string | undefined | Optional | |
haptic | HapticFeedback | undefined | Optional | Haptic feedback for value changes. Defaults to `true` (`selection`).Source default: true |
testId | string | undefined | Optional | Selector on the `role="checkbox"` button; the chip inside is decorative and carries none. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A round multi-select control (role="checkbox") for choosing any number of items from a set.
Fully controlled — pass checked and update it from onChange.
When to use
Reach for Checkbox when the user picks zero-or-more items from a set — list rows, consent
options, filters — or opts into something that is only committed when a form is submitted. The
neighbours it is most confused with are Toggle and Radio:
- Flipping a single setting that takes effect immediately (notifications on/off)? Use
Toggle— a checkbox implies a pending, batch-committed choice, a switch implies an instant one. - Choosing exactly one option from a mutually exclusive set? Use
Radio(usually viaRadioGroup).
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- control
- Label
- Control
- Description
- Owns checkbox semantics, focus treatment, interaction, and disabled behavior.
- Id
- selection-chip
- Label
- Selection chip
- Description
- Uses the shared internal selection visual without exposing it as a standalone public component.
- Id
- check
- Label
- Check glyph
- Description
- Appears only while the controlled value is checked.
Allowed Design Choices
- Variants
- Base
- Label
- Base
- Description
- Checkbox has one round visual treatment.
- Sizes
Variants
- Id
- base
- Label
- Base
- Description
- A round binary multi-select control.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- control-diameter
- Label
- Control diameter
- Kind
- exact
- Token
- --cds-size-32
- Value
- 32
- Unit
- px
- Applies To
- control
- selection-chip
- Id
- focus-ring-width
- Label
- Focus ring width
- Kind
- exact
- Token
- --cds-border-width-focus
- Value
- 3
- Unit
- px
- Applies To
- control
- keyboard-focus
Layout
- Alignment
- The check glyph is centered inside the circular selection chip.
- Flow
- The bare control is inline; visible copy is composed beside it by a parent.
- Notes
- Use Checkbox for independent selections and Toggle for settings that take effect immediately.
Typography And Color
- Typography
- Label
- Composed label
- Description
- A visible label beside the bare control uses the body ramp.
- Token
- --cds-type-body-size
- Colors
- Label
- Unchecked chip
- Description
- Uses the neutral selection-off container role.
- Token
- --cds-selection-off-container
- Label
- Checked chip
- Description
- Uses the theme-aware bold fill.
- Token
- --cds-bg-bold
- Label
- Checked glyph
- Description
- Maintains contrast on the checked fill.
- Token
- --cds-text-on-bold
- Label
- Focus ring
- Description
- Uses the brand accent for keyboard focus.
- Token
- --cds-brand
States
- Id
- unchecked
- Label
- Unchecked
- Description
- Shows the neutral empty chip and reports aria-checked false.
- Id
- checked
- Label
- Checked
- Description
- Shows the bold chip with a check and reports aria-checked true.
- Id
- disabled-unchecked
- Label
- Disabled unchecked
- Description
- Keeps the unchecked value visible while blocking changes.
- Id
- disabled-checked
- Label
- Disabled checked
- Description
- Keeps the checked value visible while blocking changes.
- Id
- keyboard-focus
- Label
- Keyboard focus
- Description
- Shows the brand focus ring around the circular control.
Behavior
- Label
- Controlled value
- Description
- Request the opposite checked value once per enabled press; the parent owns the resulting state.
- Label
- Disabled
- Description
- Do not invoke the change callback or haptic feedback while disabled.
Accessibility
- Label
- Checkbox semantics
- Description
- Expose checkbox role, the controlled checked value, and native disabled behavior.
- Label
- Accessible name
- Description
- Associate a visible label or provide an accessible label when the control appears alone.
Content Adaptation
- Label
- Visible copy
- Description
- Keep explanatory copy outside the control so it can wrap without changing the circular geometry.
Motion Haptics
- Motion
- Label
- Selection change
- Description
- Change the chip fill and check visibility without layout movement.
- Haptics
- Label
- Selection feedback
- Description
- Request the selection haptic after an enabled value change unless feedback is disabled.