Toggle Switch
A toggle switch component for binary on/off states, with support for multiple sizes and label positions.
Basic Example
Checked by Default
Sizes
Label Position
With Helper Text
Switch to dark theme for better nighttime viewing
Error State
You must enable 2FA to continue
Disabled
Combined Examples
Automatically save your work every 5 minutes
Receive notifications on your device
Increase contrast for better readability
Props
| Name | Type | Default | Description |
|---|---|---|---|
label* | string | - | Toggle switch label text |
checked | boolean | - | Controlled checked state |
defaultChecked | boolean | false | Uncontrolled default checked state |
disabled | boolean | false | Whether toggle is disabled |
error | string | - | Error message to display |
helperText | string | - | Helper text below toggle |
size | 'sm' | 'md' | 'lg' | 'md' | Size of the toggle switch |
labelPosition | 'left' | 'right' | 'right' | Position of label relative to toggle |
onChange | (e: ChangeEvent) => void | - | Change event handler |
Usage Guidelines
When to use
- •For settings that take effect immediately (no save button needed)
- •For binary on/off or enabled/disabled states
- •In settings panels and preferences menus
- •When the change is applied immediately and is reversible
Best practices
- •Use clear labels that describe what the toggle controls
- •Provide helper text to explain what happens when toggled
- •Use consistent label positioning throughout your interface
- •Show the current state visually with color and position
- •Use error states to indicate when a toggle is required but not enabled
Accessibility
- •Keyboard accessible with Tab for focus, Space or Enter to toggle
- •Uses role="switch" and aria-checked for screen readers
- •Error messages announced with aria-live and aria-invalid
- •Visual focus indicators with 2px ring for keyboard navigation
- •Label properly associated with switch via aria-describedby
- •Disabled state indicated with aria-disabled attribute
Do's and Don'ts
✓ Do
- •Use for settings that take effect immediately
- •Provide clear labels that describe the current state
- •Add helper text to explain the effect of toggling
- •Use for reversible actions only
Receive updates about your account
✗ Don't
- •Don't use for actions that require confirmation (use Checkbox)
- •Don't use for irreversible or destructive actions
- •Don't use vague labels like "Setting 1" or "Option A"
- •Don't use when changes require a save action
Related Components
Checkbox
For selecting multiple options or confirming actions
Radio
For selecting one option from multiple choices
Select
For choosing from a dropdown list of options