Toggle
On/off switch built as an accessible button
Category: inputs · WCAG 2.2-AA · switch, form, boolean
Sizes
- sm
- md
States
- off
- on
Props
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | — | Whether the control is checked (controlled). |
defaultChecked | boolean | false | Whether the control is checked on first render (uncontrolled). |
onValueChange | (checked: boolean) => void | — | Called with the new checked state when the switch is toggled. |
onChange | (checked: boolean) => void | — | Deprecated: use onValueChange (same checked boolean). |
label | string | — | Visible text label beside the switch; it also becomes the accessible name. When a heading already labels the control, omit this and pass aria-label instead to avoid duplicated text. |
size | 'sm' | 'md' | md | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
disabled | boolean | false | When true, disables the control and removes it from the tab order. |
Design tokens
--cascivo-color-accent--cascivo-color-border-strong--cascivo-color-surface--cascivo-radius-full--cascivo-focus-ring
When to use
- Flipping a single binary setting that takes effect immediately (e.g. notifications on/off)
- On/off state where a physical switch metaphor reads better than a checkmark
- Settings screens where the change applies live without a separate submit
When not to use
- Selecting items in a form that is submitted later — use Checkbox
- Choosing one option among several mutually exclusive labels — use SegmentedControl or Radio
How to build an accessible Toggle in React →
Examples
Uncontrolled
<Toggle label="Notifications" defaultChecked />Controlled
<Toggle checked={enabled} onValueChange={setEnabled} label="Dark mode" />Related components
- Checkbox — Use for form selections submitted later rather than instant settings
- SegmentedControl — Use when choosing among several exclusive options, not just on/off