Skip to content

Switch

Turns a setting on or off immediately, with its label on the inline-end side and optional help text.

betaReact AriaSource

Installation

pnpm add @syntara/react @syntara/tokens
import { Switch } from '@syntara/react';

Usage

import { Switch } from '@syntara/react';

export function Alerts() {
  return (
    <Switch defaultSelected description="Get a notification for every card payment.">
      Payment alerts
    </Switch>
  );
}

Examples

Settings list

Label plus description, linked with aria-describedby.

Get a push notification for every card payment.
Blocks online and international card payments until you turn it off.
Round up purchases and save the change.

Controlled and disabled

Accessibility

KeysAction
SpaceToggles the switch.
TabMoves focus to the switch.
  • Uses a native checkbox with role switch; the on/off state is announced.
  • State shows by thumb position and track fill, not colour alone; the off track (border.strong) meets 3:1 against the surface.
  • The thumb moves toward the inline end, so it mirrors in right-to-left layouts.
  • Rows are at least 24px tall and the label is part of the target.

Guidelines

Do

  • Use for settings that take effect immediately.
  • Label the setting, not the state: "Payment alerts", not "On".

Don’t

  • Don't use a switch in a form that needs a Submit button; use a Checkbox.
  • Don't change the label text when toggling.

API reference

Switch

children
ReactNode

The label. Without one, pass aria-label.

description
ReactNode

Help text under the label, linked with aria-describedby.

isSelected / defaultSelected
boolean

Controlled / uncontrolled on state.

onChange
(isSelected: boolean) => void

Called when toggled.

isDisabled
boolean

Disables the switch.

Default false

isReadOnly
boolean

Focusable but can't be changed.

Default false

Tokens

The semantic tokens this component reads, grouped by what they control. Swatches show this site’s theme; change a tenant’s brand and the component follows with no code change.

Colour8
action.primary.bgaction.primary.fgaction.primary.hoverborder.strongfocus.ringtext.defaulttext.disabledtext.subtle
Type2
font.size.mdline-height.normal
Space and size2
space.2space.6
Shape1
radius.pill
Depth2
shadow.highlightshadow.raised
Motion4
motion.duration.fastmotion.duration.springmotion.easingmotion.spring