Skip to main content

Switch

An on or off setting that applies at once, with no submit.

In Content first

See it live​

Start Storybook to see it live: npm run storybook
Live from StorybookOpen Switch in StorybookSee it in dark

When to use it​

In Content first: A setting that applies at once, such as emailing the weekly letter. Not for a choice that waits for a form.

  • Use it when: A setting that should take effect as soon as it is flipped.
  • Not when: A choice that waits for a form (checkbox).

Instead:

  • Checkbox: Waits for the form.
  • Toggle: A pressed button in a toolbar.

Words​

  • Write to one person: "you", not "users".
  • Short sentences with room to breathe.
  • Explain why before asking for anything.
  • Use: Read, Save for later, You, Next issue. Avoid: Click here, Submit, Users, Content.

The labels components use, from the voice tokens:

  • content.action.commit: Save
  • content.action.cancel: Not now
  • content.action.destroy: Remove
  • content.action.retry: Try again
  • content.action.empty-action: Browse guides

See Voice and tone for the whole voice.

Accessibility and keyboard​

KeyboardWhat happensNot
undefinedSpace flips it.undefined

Test before you ship:

  • It is a switch with a visible label; on and off are announced. undefined

Use it in code​

npx open-ds add switch

The component reads only component keys and semantic tokens, so it follows the brand and mode on <html>.

Tokens it reads​

Switch reads 15 tokens of its own, each an alias of a semantic token. Each row is one part: its own token, the semantic it aliases, and the value it ends at. Change a semantic and every component that reads it follows; override one of Switch's tokens to change Switch alone.

Changes with theme

Content first decides what changes when you switch theme. Here a switch changes colors only, so the marked rows differ between light and dark; everything else holds steady.

PartIts token and the semantic it aliasesValue
Shared
Button focus ring
Changes with theme
on focus		component.button.focus-ringcolor.border.focusvar(--button-focus-ring)Lightnavy.light.600:#1E3A5FDarknavy.dark.600:#8FA6C4
Control checked
Changes with theme
when on		component.control.checkedcolor.action.primaryvar(--control-checked)Lightnavy.light.600:#1E3A5FDarknavy.dark.600:#8FA6C4
Control track
Changes with theme		component.control.trackcolor.border.strongvar(--control-track)Lightstone.light.500:#7A7062Darkstone.dark.400:#A39A8B
Control thumb
Changes with theme		component.control.thumbcolor.surface.defaultvar(--control-thumb)Lightstone.light.0:#FFFFFFDarkstone.dark.50:#1F1B16
Transition durationcomponent.transition.durationmotion.duration.feedbackvar(--transition-duration)duration.moderate:200ms
Transition easingcomponent.transition.easingmotion.easing.standardvar(--transition-easing)easing.standard:cubic-bezier(0.2,0,0,1)
Switch
Heightcomponent.switch.heightsize.iconvar(--switch-height)size.16:1rem
Widthcomponent.switch.widthsize.iconvar(--switch-width)size.16:1rem
Cornercomponent.switch.radiusradius.roundvar(--switch-radius)radius.full:9999px
Paddingcomponent.switch.paddingcomponent-spacing-map.hairlinevar(--switch-padding)space.2:0.125rem
Focus
on focus		component.switch.focusborder-width.focusvar(--switch-focus)border-width.2:2px
Disabled
when disabled		component.switch.disabledopacity.disabledvar(--switch-disabled)opacity.40:0.4
Canvas
Changes with theme
on focus		component.switch.canvascolor.surface.canvasvar(--switch-canvas)Lightstone.light.50:#FFFDF8Darkstone.dark.0:#14110D
Sizecomponent.switch.sizesize.iconvar(--switch-size)size.16:1rem
Icon
when on		component.switch.iconsize.iconvar(--switch-icon)size.16:1rem