Toggle

On/off switch built as an accessible button

Category: inputs · WCAG 2.2-AA · switch, form, boolean

Sizes

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.
`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.
`ariaLabel`	`string`	—	Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is visible; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this.

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

Selecting items in a form that is submitted later — use Checkbox
Choosing one option among several mutually exclusive labels — use SegmentedControl or Radio

<Toggle label="Notifications" defaultChecked />

<Toggle checked={enabled} onValueChange={setEnabled} label="Dark mode" />

Checkbox — Use for form selections submitted later rather than instant settings
SegmentedControl — Use when choosing among several exclusive options, not just on/off