Switch
A switch turns a setting on or off the moment the traveller flips it, and it shows its own busyness while the change applies.
Installation
npx shadcn@latest add @flyingsalmon/switchUsage
import { useState } from 'react'
import { Switch } from '@/components/ui/switch'
export function SwitchUsage() {
const [offlineMaps, setOfflineMaps] = useState(false)
return (
<Switch
label="Offline maps"
checked={offlineMaps}
onCheckedChange={setOfflineMaps}
/>
)
}Examples
Sizes
Default and small match the two field heights, so a switch lines up with the input beside it. The label stays the same size at both.
Without a label
Drop the label when a row already names the setting, and pass aria-label so the switch keeps an accessible name.
- Alfama walking tour
- Time Out Market lunch
Loading
Loading pulses the thumb and ignores clicks and keys, while focus stays where it is. The thumb sits wherever checked puts it.
Disabled
Disabled dims the track and the label together. Use it when the setting cannot change at all, and loading when a change is in flight.
Confirm first
Flip the switch. It loads and the thumb stays put until the call returns, then moves. The app controls checked and sets loading while the call runs.
A failed toggle
The call fails, so the switch stays off and the failure appears beside it with a retry. A failed toggle is an action result, not a field error, so the result lives on the setting itself.
In a row of fields
A row of fields aligns its controls to the bottom edge. A switch of the same size is exactly one box tall, so it lines up with the fields beside it without extra classes.
Guidelines
When to use
- For a setting that takes effect the moment it flips, such as offline maps or link sharing.
- For an on or off state the traveller will want to see at a glance.
When not to use
- Use Checkbox for a yes or no that a form collects and submits later. A checkbox says the value waits for a submit.
- Use Toggle group to choose between two named options such as "Day" and "Night". A switch means on or off, not this or that.
- Use Button for an action that runs once and has no state to show.
Do and don’t
- DoLabel the switch with the setting, not the state: "Offline maps", not "Turn on offline maps".The thumb already shows on or off, so a label that names the state can contradict it.
- DoPut the switch on the row of the thing it changes, such as "For the whole group" beside a budget.The traveller sees the setting and its effect together, and the figure beside it changes the moment the switch flips.
- DoMove the thumb when a saved change lands, and leave it where it was if the change fails.The switch never claims a state the server does not hold, so what the traveller sees is what is saved.
- Don’tShow a failed toggle as an error on the switch.A failed toggle is an action result, not a field error. It appears on the setting’s row with a retry, where the traveller is already looking.
- Don’tGrey out a switch while its change applies.The thumb pulses, focus stays put, and repeat presses are ignored. A greyed-out switch drops focus mid-action and looks unavailable.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves focus to the switch. A loading switch stays in the tab order; a disabled one leaves it. |
| SpaceEnter | Toggles the switch. A loading switch ignores both. |
Clicking the label toggles the setting. The focus ring appears on keyboard focus only. A loading switch announces aria-disabled rather than aria-busy, which screen readers support poorly, and it never sets the disabled attribute, which would drop it from the tab order. The accessibility page covers the rules every component follows.
API
Switch
Every other prop passes through to the Radix switch root. For a setting the server holds, control checked, set loading while the call runs, and keep the old value when the call fails. There is no error prop: a failed toggle shows on the setting’s row.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | – | The text beside the switch. It is part of the click target. Without it, pass aria-label. |
| size | SwitchSize | SwitchSize.Default | Default and Small match the field heights of the same names. |
| checked | boolean | – | The on state when the app controls it. |
| defaultChecked | boolean | false | The starting state when the app does not control it. |
| onCheckedChange | (checked: boolean) => void | – | Called with the requested state after each toggle. |
| loading | boolean | false | Pulses the thumb and ignores clicks and keys while keeping focus. Set it, not disabled, while the change applies: disabled leaves the tab order and drops focus mid-action. |
| disabled | boolean | false | Dims the switch and its label and removes it from the tab order. |
| className | string | – | Styles the wrapper that holds the track and the label, not the track itself. |