# Checkbox A controlled round multi-select control that toggles one item without committing an entire form. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx ## Guidance { "summary": "A controlled round multi-select control that toggles one item without committing an entire form.", "guidance": [ { "heading": "Overview", "body": "A round multi-select control (`role=\"checkbox\"`) for choosing any number of items from a set.\nFully controlled — pass `checked` and update it from `onChange`." }, { "heading": "When to use", "body": "Reach for `Checkbox` when the user picks zero-or-more items from a set — list rows, consent\noptions, filters — or opts into something that is only committed when a form is submitted. The\nneighbours it is most confused with are `Toggle` and `Radio`:\n\n- Flipping a **single setting that takes effect immediately** (notifications on/off)? Use `Toggle` —\n a checkbox implies a pending, batch-committed choice, a switch implies an instant one.\n- Choosing **exactly one option** from a mutually exclusive set? Use `Radio` (usually via\n `RadioGroup`)." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/primitives/Checkbox/Checkbox.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "checked", "type": "boolean", "declared_type": "boolean", "required": true, "description": "Current state, exposed as `aria-checked`.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 14 }, "values": [ false, true ], "values_complete": true }, { "name": "onChange", "type": "((checked: boolean) => void) | undefined", "declared_type": "(checked: boolean) => void", "required": false, "description": "Called with the next checked value when pressed.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 16 } }, { "name": "disabled", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Blocks the press and dims the chip.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 18 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label when no visible label is associated with the checkbox.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 20 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 21 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for value changes. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 23 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the `role=\"checkbox\"` button; the chip inside is decorative and carries none.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 25 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Checkbox", "public_path": "Checkbox", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Checkbox", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 31 }, "props_type": "CheckboxProps", "props": [ { "name": "checked", "type": "boolean", "declared_type": "boolean", "required": true, "description": "Current state, exposed as `aria-checked`.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 14 }, "values": [ false, true ], "values_complete": true }, { "name": "onChange", "type": "((checked: boolean) => void) | undefined", "declared_type": "(checked: boolean) => void", "required": false, "description": "Called with the next checked value when pressed.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 16 } }, { "name": "disabled", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Blocks the press and dims the chip.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 18 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label when no visible label is associated with the checkbox.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 20 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 21 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for value changes. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 23 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the `role=\"checkbox\"` button; the chip inside is decorative and carries none.", "source": { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 25 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/Checkbox/Checkbox.tsx", "line": 12, "name": "CheckboxProps", "code": "export interface CheckboxProps {\n /** Current state, exposed as `aria-checked`. */\n checked: boolean;\n /** Called with the next checked value when pressed. */\n onChange?: (checked: boolean) => void;\n /** Blocks the press and dims the chip. */\n disabled?: boolean;\n /** Accessible label when no visible label is associated with the checkbox. */\n ariaLabel?: string;\n className?: string;\n /** Haptic feedback for value changes. Defaults to `true` (`selection`). */\n haptic?: HapticFeedback;\n /** Selector on the `role=\"checkbox\"` button; the chip inside is decorative and carries none. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Checkbox", "status": "preview", "version": "2.0.0", "summary": "A controlled round multi-select control that toggles one item without committing an entire form." }, "parts": [ { "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." } ], "allowedDesignChoices": { "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": [], "measurements": [ { "id": "control-diameter", "label": "Control diameter", "kind": "exact", "token": "--cds-size-32", "value": 32, "unit": "px", "appliesTo": [ "control", "selection-chip" ] }, { "id": "focus-ring-width", "label": "Focus ring width", "kind": "exact", "token": "--cds-border-width-focus", "value": 3, "unit": "px", "appliesTo": [ "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." ] }, "typographyAndColor": { "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." } ], "contentAdaptation": [ { "label": "Visible copy", "description": "Keep explanatory copy outside the control so it can wrap without changing the circular geometry." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-size-32", "light": "32px", "dark": "32px" }, { "name": "--cds-border-width-focus", "light": "3px", "dark": "3px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-selection-off-container", "light": "#e0ddd6", "dark": "#ffffff26" }, { "name": "--cds-bg-bold", "light": "#0b0b0a", "dark": "#ffffff" }, { "name": "--cds-text-on-bold", "light": "#ffffff", "dark": "#141410" }, { "name": "--cds-brand", "light": "#ff550c", "dark": "#ff550c" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Playground](/storybook/iframe.html?id=cloaked-design-system-primitives-checkbox--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/Checkbox/Checkbox.stories.tsx - [Unchecked](/storybook/iframe.html?id=cloaked-design-system-primitives-checkbox--unchecked&viewMode=story) | export: Unchecked | source: packages/design-system/src/components/primitives/Checkbox/Checkbox.stories.tsx - [Checked](/storybook/iframe.html?id=cloaked-design-system-primitives-checkbox--checked&viewMode=story) | export: Checked | source: packages/design-system/src/components/primitives/Checkbox/Checkbox.stories.tsx - [Disabled](/storybook/iframe.html?id=cloaked-design-system-primitives-checkbox--disabled&viewMode=story) | export: Disabled | source: packages/design-system/src/components/primitives/Checkbox/Checkbox.stories.tsx - [States](/storybook/iframe.html?id=cloaked-design-system-primitives-checkbox--states&viewMode=story) | export: States | source: packages/design-system/src/components/primitives/Checkbox/Checkbox.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-primitives-checkbox--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/primitives/Checkbox/Checkbox.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.