Skip to content
flyingsalmon

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/switch

Usage

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

  • Do
    Label 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.
  • Do
    Put 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.
  • Do
    Move 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’t
    Show 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’t
    Grey 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

KeyDescription
TabMoves focus to the switch. A loading switch stays in the tab order; a disabled one leaves it.
SpaceEnterToggles 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.

PropTypeDefaultDescription
labelstring–The text beside the switch. It is part of the click target. Without it, pass aria-label.
sizeSwitchSizeSwitchSize.DefaultDefault and Small match the field heights of the same names.
checkedboolean–The on state when the app controls it.
defaultCheckedbooleanfalseThe starting state when the app does not control it.
onCheckedChange(checked: boolean) => void–Called with the requested state after each toggle.
loadingbooleanfalsePulses 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.
disabledbooleanfalseDims the switch and its label and removes it from the tab order.
classNamestring–Styles the wrapper that holds the track and the label, not the track itself.

  • Checkbox

    A yes or no that waits for a form submit.
  • Toggle group

    Chips for choosing between named options.
  • Number field

    The field a switch commonly sits beside.
  • Principles

    Where a result belongs: the feedback rule.
  • Motion

    The spring presets and timings behind the thumb.