Switch
A control that allows users to toggle between checked and not checked.
Overview
The Switch component is a UI control that allows users to toggle between two states: on and off. It's commonly used for enabling or disabling features, toggling settings, or changing modes.
Our Switch component is built with Radix UI primitives and follows WAI-ARIA best practices. It supports keyboard navigation, focus management, and screen reader announcements.
Basic Usage
The default Switch component provides a simple, accessible toggle control.
Examples
With Label
Add a label to provide context for the switch.
Disabled State
Switch can be disabled to prevent user interaction.
Form Integration
Switch can be integrated into forms for collecting user preferences.
With Icons
Add icons to provide visual context for the switch.
Controlled Example
Control the switch state programmatically.
API Reference
The Switch component provides a way to toggle between two states.
| Prop | Type | Description |
|---|---|---|
| checked | boolean | Whether the switch is checked or not. Use with onCheckedChange for controlled usage. |
| defaultChecked | boolean | The default state of the switch when initially rendered. Use for uncontrolled usage. |
| onCheckedChange | function | Event handler called when the checked state changes. |
| disabled | boolean | When true, prevents the user from interacting with the switch. |
| required | boolean | When true, indicates that the user must check the switch before the form can be submitted. |
| name | string | The name of the switch. Submitted with its owning form as part of a name/value pair. |
| value | string | The value given as data when submitted with a name. |
The Switch component also accepts all standard HTML attributes for the button element.
Usage Guidelines
Follow these guidelines for effective use of the Switch component:
Best Practices
Do
- Use switches for binary settings (on/off, enabled/disabled)
- Provide clear labels that describe what the switch controls
- Use switches for settings that take immediate effect
- Group related switches together
- Consider using a default state that is the safest or most common option
Don't
- Use switches for actions that should be buttons
- Use switches for options that require confirmation before taking effect
- Use switches without clear labels
- Use switches for mutually exclusive options (use radio buttons instead)
- Use switches when a checkbox would be more appropriate (e.g., for agreement to terms)
Switch vs. Checkbox vs. Toggle
While switches, checkboxes, and toggles may seem similar, they have distinct use cases:
| Component | Best Used For | Examples |
|---|---|---|
| Switch | Binary settings with immediate effect | Dark mode, notifications on/off, airplane mode |
| Checkbox | Selection, agreement, or optional items | Terms agreement, multi-select lists, "Remember me" |
| Toggle | UI state changes or mode selection | Bold/italic text, showing/hiding panels, view modes |
Accessibility
The Switch component follows WAI-ARIA guidelines to ensure accessibility.
Keyboard Navigation
Users can navigate to switches using the Tab key and toggle them using the Space key.
Screen Readers
The component uses proper ARIA attributes to communicate state changes to assistive technologies.
Accessibility Tip
Always associate labels with switches using the htmlFor attribute that matches the switch's id. This ensures that users can click on the label to toggle the switch, and screen readers can announce the label when the switch is focused.