# Toggle

A controlled solid switch for a single setting that takes effect immediately.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/primitives/Toggle/Toggle.tsx

## Guidance

{
  "summary": "A controlled solid switch for a single setting that takes effect immediately.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A solid iOS-style switch (`role=\"switch\"`) for a single setting that takes effect the moment it\nflips. Fully controlled — pass `checked` and update it from `onChange`."
    },
    {
      "heading": "When to use",
      "body": "Reach for `Toggle` when flipping the switch is the action itself — notifications, a feature\nenable/disable — with no separate save step. The distinction from `Checkbox` is the commit model,\nnot the shape: a switch applies instantly, while a checkbox marks an opt-in that a form submit\ncommits later. Selecting several items from a set, or anything staged until submit, is `Checkbox`\nterritory."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/primitives/Toggle/Toggle.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/Toggle/Toggle.tsx",
        "line": 19
      },
      "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/Toggle/Toggle.tsx",
        "line": 21
      }
    },
    {
      "name": "disabled",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Blocks the press and dims the whole switch.",
      "source": {
        "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
        "line": 23
      },
      "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 switch.",
      "source": {
        "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
        "line": 25
      }
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
        "line": 26
      }
    },
    {
      "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/Toggle/Toggle.tsx",
        "line": 28
      },
      "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=\"switch\"` button; assert state with `aria-checked`.",
      "source": {
        "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
        "line": 30
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Toggle",
    "public_path": "Toggle",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Toggle",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
          "line": 37
        },
        "props_type": "ToggleProps",
        "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/Toggle/Toggle.tsx",
              "line": 19
            },
            "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/Toggle/Toggle.tsx",
              "line": 21
            }
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Blocks the press and dims the whole switch.",
            "source": {
              "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
              "line": 23
            },
            "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 switch.",
            "source": {
              "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
              "line": 25
            }
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
              "line": 26
            }
          },
          {
            "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/Toggle/Toggle.tsx",
              "line": 28
            },
            "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=\"switch\"` button; assert state with `aria-checked`.",
            "source": {
              "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
              "line": 30
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/primitives/Toggle/Toggle.tsx",
        "line": 17,
        "name": "ToggleProps",
        "code": "export interface ToggleProps {\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 whole switch. */\n    disabled?: boolean;\n    /** Accessible label when no visible label is associated with the switch. */\n    ariaLabel?: string;\n    className?: string;\n    /** Haptic feedback for value changes. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    /** Selector on the `role=\"switch\"` button; assert state with `aria-checked`. */\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": "Toggle",
      "status": "preview",
      "version": "2.0.0",
      "summary": "A controlled solid switch for a single setting that takes effect immediately."
    },
    "parts": [
      {
        "id": "track",
        "label": "Track",
        "description": "Owns switch semantics, selected color, interaction, and disabled treatment."
      },
      {
        "id": "knob",
        "label": "Knob",
        "description": "Slides between the leading and trailing inset to represent the controlled value."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "Toggle has one solid switch treatment."
        }
      },
      "sizes": {}
    },
    "variants": [
      {
        "id": "base",
        "label": "Base",
        "description": "A solid fully rounded track with a sliding circular knob.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "track-radius",
        "label": "Track and knob radius",
        "kind": "exact",
        "token": "--cds-radius-full",
        "value": "full",
        "unit": "none",
        "appliesTo": [
          "track",
          "knob"
        ]
      },
      {
        "id": "track-width",
        "label": "Track width",
        "kind": "example-only",
        "value": 51,
        "unit": "px",
        "appliesTo": [
          "track"
        ],
        "notes": "The current implementation follows the iOS inline-switch proportion."
      },
      {
        "id": "track-height",
        "label": "Track height",
        "kind": "example-only",
        "value": 31,
        "unit": "px",
        "appliesTo": [
          "track"
        ]
      },
      {
        "id": "knob-size",
        "label": "Knob size",
        "kind": "example-only",
        "value": 27,
        "unit": "px",
        "appliesTo": [
          "knob"
        ]
      }
    ],
    "layout": {
      "alignment": "The knob stays vertically centered with equal inset at either end of the track.",
      "flow": "The bare switch is inline; a parent composes visible setting copy beside it.",
      "notes": [
        "Use Checkbox when selecting items from a set or deferring commitment until form submission."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Composed label",
          "description": "A visible setting label beside the bare switch uses the body ramp.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Off track",
          "description": "Uses the neutral toggle off-track role, a step darker than the selection chip in light mode.",
          "token": "--cds-toggle-off-container"
        },
        {
          "label": "On track",
          "description": "Uses the solid success role.",
          "token": "--cds-status-success-solid"
        },
        {
          "label": "Knob",
          "description": "Uses the fixed inverse foreground role for a light knob.",
          "token": "--cds-text-inverse"
        },
        {
          "label": "Knob shadow",
          "description": "Uses the scrim role as the shadow color source.",
          "token": "--cds-scrim"
        }
      ]
    },
    "states": [
      {
        "id": "off",
        "label": "Off",
        "description": "Shows the neutral track, leading knob, and aria-checked false."
      },
      {
        "id": "on",
        "label": "On",
        "description": "Shows the success track, trailing knob, and aria-checked true."
      },
      {
        "id": "disabled-off",
        "label": "Disabled off",
        "description": "Keeps the off value visible while blocking changes."
      },
      {
        "id": "disabled-on",
        "label": "Disabled on",
        "description": "Keeps the on value visible while blocking changes."
      },
      {
        "id": "reduced-motion",
        "label": "Reduced motion",
        "description": "Moves the knob to the next resting position without a transition."
      }
    ],
    "behavior": [
      {
        "label": "Controlled value",
        "description": "Request the opposite checked value once per enabled press; the parent owns the resulting state."
      },
      {
        "label": "Immediate setting",
        "description": "Use the control only when changing the switch takes effect immediately."
      },
      {
        "label": "Disabled",
        "description": "Do not invoke the change callback or haptic feedback while disabled."
      }
    ],
    "accessibility": [
      {
        "label": "Switch semantics",
        "description": "Expose switch role, the controlled checked value, and native disabled behavior."
      },
      {
        "label": "Accessible name",
        "description": "Associate a visible setting label or provide an accessible label when the switch appears alone."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Visible copy",
        "description": "Keep setting copy outside the fixed switch so it can wrap and localize independently."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Knob transition",
          "description": "Slide the knob and transition the track color together; remove both transitions for reduced motion."
        }
      ],
      "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-radius-full",
      "light": "9999px",
      "dark": "9999px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-toggle-off-container",
      "light": "#c4c2bc",
      "dark": "#ffffff26"
    },
    {
      "name": "--cds-status-success-solid",
      "light": "#008924",
      "dark": "#008924"
    },
    {
      "name": "--cds-text-inverse",
      "light": "#ffffff",
      "dark": "#ffffff"
    },
    {
      "name": "--cds-scrim",
      "light": "#0b0b0a",
      "dark": "#0b0b0a"
    }
  ],
  "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-toggle--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/Toggle/Toggle.stories.tsx

- [Off](/storybook/iframe.html?id=cloaked-design-system-primitives-toggle--off&viewMode=story) | export: Off | source: packages/design-system/src/components/primitives/Toggle/Toggle.stories.tsx

- [On](/storybook/iframe.html?id=cloaked-design-system-primitives-toggle--on&viewMode=story) | export: On | source: packages/design-system/src/components/primitives/Toggle/Toggle.stories.tsx

- [Disabled](/storybook/iframe.html?id=cloaked-design-system-primitives-toggle--disabled&viewMode=story) | export: Disabled | source: packages/design-system/src/components/primitives/Toggle/Toggle.stories.tsx

- [States](/storybook/iframe.html?id=cloaked-design-system-primitives-toggle--states&viewMode=story) | export: States | source: packages/design-system/src/components/primitives/Toggle/Toggle.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-primitives-toggle--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/primitives/Toggle/Toggle.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.