Components / Controls

Switch

An on/off setting that takes effect straight away, such as "Auto-expand". It is built on a native checkbox with role="switch". If the choice is confirmed later with a submit button, use Checkbox.

Source Edit this page

Toggles as aswitch

When to use

A preference or feature that is on or off and applies immediately.
Settings lists with a short description under each label.

Use something else when:

the value is part of a form that is submitted or confirmed: Checkbox
the user picks one of several options: RadioGroup or SegmentedControl
it is an action, not a setting: Button

Usage

tsx

import { Switch } from "@arshad-shah/cynosure";

<Switch label="Auto-expand" checked={auto} onChange={setAuto} />
<Switch label="Notifications" description="Email me about new comments" defaultChecked />
<Switch label="Beta features" tone="warning" disabled />

onChange receives the new boolean. Use checked for controlled state or defaultChecked for uncontrolled.

Options

description: supporting text under the label.
size: sm, md or lg.
tone: colours the track when on: accent (default), neutral, danger, success, warning or info.
name and value: native, so the switch submits with a form.

A Switch has no strikeWhenChecked: that checklist style belongs to Checkbox. A switch that is on keeps a plain label.

Props

Every prop of Switch
Prop	What it does	Type	Default
`label`Required	The control's label. Pressing it toggles the control.	`ReactNode`
`description`	Help text shown under the label and read with the control.	`ReactNode`
`checked`	Controlled: whether it is on.	`boolean`
`defaultChecked`	On at first, when uncontrolled.	`boolean`
`onChange`	Called when the person turns it on or off, with the new state.	`((checked: boolean) => void)`
`name`	Name it is submitted under in a form, when on.	`string`
`value`	The value submitted with `name` when on. The browser sends "on" when this is not set.	`string`
`required`	It must be on for the form to submit.	`boolean`
`disabled`	It cannot be changed and is not submitted with a form.	`boolean`
`size`	Size of the control and its text. Default "md".	`Size`	`"md"`
`tone`	Fill colour when on. Default "accent".	`Tone`	`"accent"`
`id`	Id of the native input; one is generated when not set.	`string`
`className`	Added to the root element (the label that wraps the row), for layout.	`string`
`style`	Layout only, applied to the root element.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Input	Result
Click, tap, `SpaceSpace`	Toggles
`TabTab`	Focus with a visible ring

Native checkbox: forms, reset, required and keyboard behaviour match Checkbox, without the mixed state.
Role: it is announced as a switch with its checked state.
Motion: the thumb slides, and stops animating under reduced motion.

Theming

Tokens: --cy-switch-{width,height,thumb-size,off-bg}, and --cy-switch-height-sm and --cy-switch-height-lg for the other sizes. The row around the switch is a Choice: --cy-choice-gap is the space before the label.

createTheme({ components: { switch: { width: "44px", offBg: "#cbd5e1" } } });

Checkbox · Choice · RadioGroup · SegmentedControl

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

OptionsLink to "Options"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"