Switch

Binary setting with on and off states.

Overview

  • Use a switch for a setting that takes effect immediately. Use a checkbox when changes require form submission.

Aliases

toggle

When to use

  • Use Switch for settings that take effect immediately.
  • Describe what the enabled setting does.

When not to use

  • Do not use Switch for form checklists or consent flows; use Checkbox instead.
  • Use Checkbox for settings that take effect after form submission.

Structural parts

toggle shell

track

Carries the on/off background state.

moving indicator

thumb

Shows the binary position of the switch.

visible label

label

Names the system state being toggled.

supporting copy

description

Optional explanation of the toggle effect.

Public interface

Props
NameTypeDefaultDescription
checkedbooleanfalseControlled on/off state.
labelstring—Visible switch label.
descriptionstring—Supporting explanation of the toggle effect.
disabledbooleanfalseDisables the switch.
namestring—Native form field name.
idstring—Optional explicit id.
size'sm' | 'md''md'Chooses the switch size recipe.
onChange(detail: { checked: boolean }) => void—Receives the new checked state after activation.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
change{ checked: boolean }Fires with the checked state.
Slots
NameDescription
defaultSwitch is prop-driven and does not expose custom slots.

Variants, sizes, and states

Variants

  • default: Switch uses one structural recipe and varies by size.

Sizes

  • sm: Compact switch
  • md: Default switch size

States

  • off: Default off position.
  • on: Enabled on position.
  • disabled: Semantically disabled and visually inactive.

Accessibility

Semantics

  • Uses switch semantics for an on/off stateful control.

Keyboard

  • Supports native focus and Space activation behavior.

Screen readers

  • Visible label and description explain what the on/off state means.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-switch-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-switch-hit-size
44px
--dk-motion-duration
200ms

track

--dk-switch-track-bg
#95989d
--dk-switch-track-width
42px
--dk-switch-track-height
24px
--dk-switch-track-radius
999px
--dk-switch-thumb-offset
2px
--dk-switch-focus-ring-color
#2072e4

thumb

--dk-switch-thumb-bg
#f2f5fb
--dk-switch-thumb-size
20px

label

--dk-switch-label-color
#16181c
--dk-switch-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-switch-label-weight
600

description

--dk-switch-description-color
#16181c
--dk-switch-description-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Examples

Starter

Enabled feature

A basic on/off setting.

<Switch label="Auto publish" description="Ship after checks pass." checked={true} />

Common patterns

Compact inspector toggle

Smaller switch for dense inspector layouts.

<Switch size="sm" label="Quiet mode" checked={false} />

Edge cases

Unavailable system state

Explain why a switch is unavailable when the reason is not apparent.

<Switch label="Live sync" disabled={true} />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default (size=sm)

pass

size=sm

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, motion
  • Evaluated: contrast, target, motion
  • Contrast: 53.9 Lc
  • Target: 44 px
  • Motion: 200 ms

default (size=md)

pass

size=md

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, motion
  • Evaluated: contrast, target, motion
  • Contrast: 53.9 Lc
  • Target: 44 px
  • Motion: 200 ms

default (size=lg)

pass

size=lg

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, motion
  • Evaluated: contrast, target, motion
  • Contrast: 53.9 Lc
  • Target: 44 px
  • Motion: 200 ms

checked (size=sm)

pass

size=sm

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, motion
  • Evaluated: contrast, target, motion
  • Contrast: 76.6 Lc
  • Target: 44 px
  • Motion: 200 ms

checked (size=md)

pass

size=md

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, motion
  • Evaluated: contrast, target, motion
  • Contrast: 76.6 Lc
  • Target: 44 px
  • Motion: 200 ms

checked (size=lg)

pass

size=lg

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, motion
  • Evaluated: contrast, target, motion
  • Contrast: 76.6 Lc
  • Target: 44 px
  • Motion: 200 ms