Skip to content
Cloaked Design SystemPrimitives

Toggle

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

Implementation preview
COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

6 stories
SELECTED EXAMPLE

Playground

Open controls
Playground selectedOpen canvas
Example sourcepackages/design-system/src/components/primitives/Toggle/Toggle.stories.tsxExport Playground

Implementation 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 solid switch for a single setting that takes effect immediately.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
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 { Toggle } from '@cloakedinc/design-system';
ToggleToggleProps

packages/design-system/src/components/primitives/Toggle/Toggle.tsx:37

PropTypePresenceNotes
checkedbooleanRequiredCurrent state, exposed as `aria-checked`.
onChange((checked: boolean) => void) | undefinedOptionalCalled with the next checked value when pressed.
disabledboolean | undefinedOptionalBlocks the press and dims the whole switch.
ariaLabelstring | undefinedOptionalAccessible label when no visible label is associated with the switch.
classNamestring | undefinedOptional
hapticHapticFeedback | undefinedOptionalHaptic feedback for value changes. Defaults to `true` (`selection`).Source default: true
testIdstring | undefinedOptionalSelector on the `role="switch"` button; assert state with `aria-checked`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

A solid iOS-style switch (role="switch") for a single setting that takes effect the moment it flips. Fully controlled — pass checked and update it from onChange.

When to use

Reach for Toggle when flipping the switch is the action itself — notifications, a feature enable/disable — with no separate save step. The distinction from Checkbox is the commit model, not the shape: a switch applies instantly, while a checkbox marks an opt-in that a form submit commits later. Selecting several items from a set, or anything staged until submit, is Checkbox territory.

Component specification

$schema../../../specs/component-spec.schema.json
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.
Allowed Design Choices
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
SizesNone specified
Measurements
Id
track-radius
Label
Track and knob radius
Kind
exact
Token
--cds-radius-full
Value
full
Unit
none
Applies To
  • track
  • knob
Id
track-width
Label
Track width
Kind
example-only
Value
51
Unit
px
Applies To
  • track
Notes
The current implementation follows the iOS inline-switch proportion.
Id
track-height
Label
Track height
Kind
example-only
Value
31
Unit
px
Applies To
  • track
Id
knob-size
Label
Knob size
Kind
example-only
Value
27
Unit
px
Applies To
  • 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.
Typography And Color
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.
Content Adaptation
Label
Visible copy
Description
Keep setting copy outside the fixed switch so it can wrap and localize independently.
Motion Haptics
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.
Platform DifferencesNone specified
Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1