Skip to content
WunderUI

Switch

Free

Turn one setting on or off, with an effect that applies at once.

npx wunderui-cli add switch

Playground

Installation

bash
npx wunderui-cli add switch

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { Switch } from "@/components/ui/switch"

Then use it:

tsx
import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"

export function Notifications() {
  return (
    <div className="flex items-center gap-2">
      <Switch id="notifications" defaultChecked />
      <Label htmlFor="notifications">Email notifications</Label>
    </div>
  )
}

Expected result: You see one small switch, turned on, with the label Email notifications. A click on the switch or the text turns it off.

When to use

Use Switch for

  • One setting that is on or off and takes effect at once, such as notifications
  • A row of settings, each with a title and a short description
  • A master switch that turns a group of settings on or off

Use something else for

  • Checkbox for a choice that is saved later with a form, or several choices from a list
  • Radio Group for one choice out of several named options
  • Segment for switching between views, with one always selected
  • Selector Item for a whole row with a title, a description and a switch

Appearance

Brand is the default. Neutral fills the track black in light mode and white in dark mode, and muted fills it grey, for surfaces where the brand colour would compete.

Sizes

Regular is 32 by 18 px, for forms and settings. Small is 24 by 14 px, for dense rows such as table cells; a switch has no indeterminate state.

States

Point at a switch or press Tab to see hover and the focus ring. A disabled On switch still shows the knob on the right, and while a save runs the knob shows a spinner.

Label and description

The label names the setting and never changes with the state. Put it after the switch, or before it with the switch at the far edge of a row; a description says what the setting does.

Save failed

A switch takes effect at once, so it has no invalid value. When a save fails it goes back to its previous state and a message with a retry says why.

Keyboard interactions

A switch is one tab stop. It is a button in all but name, so Space and Enter both toggle it.

TaborShiftTab
Moves focus to the next or previous switch in the order they are written. A disabled switch is skipped.
SpaceorEnter
Toggles the focused switch and calls . A switch that is or ignores both keys.

Behavior and motion

What the switch does itself, and what it leaves to the page.

Two elements, one control
The visible track is a switch element, with a hidden checkbox input beside it that carries the name, value and form state. Labels are copied onto it so page checkers see a named input.
Controlled or not
Pass a checked value and a change handler to own the value, or a default to let the switch keep it. There is no indeterminate state.
Names
A Label linked to the switch names it and makes the text a click target. Inside a Selector Item the title names it, and otherwise you pass an aria-label.
Hit area
The area that takes a click reaches 12 px to the sides and 8 px above and below the track, so a near miss still toggles it.
Hover and pressed
An off track gets a rim on hover and a darker grey while pressed, and a brand track darkens on hover and again when pressed. Disabled is the rest look at 40 % opacity.
Saving
Saving puts a spinner on the knob, marks the switch busy and makes it read-only until you clear it. Set the switch to its new value first, then clear saving when the request ends.
Save failed
A failed save is not an invalid value, so the switch is not marked invalid. Set it back to its previous value and show a message with a retry next to it, as a Selector Item error does.
In a form
With a name the switch submits its value (default on) when on, and nothing when off unless you set an unchecked value. Required asks for it to be on before the form is sent.
Motion
The track changes colour quickly and the knob slides with an overshoot, swinging slightly past the end and settling. A second click reverses it from wherever it is.
Reduced motion
With reduced motion the knob no longer slides but jumps to the other end, the colour change stays, and the spinner stays as a still glyph.

Anatomy

The parts the component is made of. Each one renders a you can target from CSS.

  • data-slot="switch"

    The track, with the switch role: 32 by 18 px by default, 24 by 14 px small. Grey when off, brand, neutral or muted when on, with a hit area that reaches 12 px sideways and 8 px up and down.

  • data-slot="switch-thumb"

    The round knob, which slides with a slight overshoot and reverses mid-way if clicked again. While saving it shows a spinner, and Switch renders it for you.

  • data-slot="switch-spinner"Optional
  • The text that names the setting, a Label linked to the switch or the title of a Selector Item, and clicking it toggles the switch. Name the setting, never the state.

  • Optional

    A table cell that puts a Switch and its text in one label, so the text also toggles it.

Best practices

  • Do

    Give every switch a visible label and link it to the switch. A click on the text then toggles it, and a screen reader announces the name with on or off.

  • Do

    Name the setting, not the state: Email notifications, not On. The switch role already tells screen readers whether it is on.

  • Do

    Set the saving state while a request runs. The knob shows a spinner and clicks are ignored until the save ends.

  • Do

    When a save fails, set the switch back to its previous value and say so in a message with a retry, like Couldn't save. Try again.

  • Do

    Use the small size in dense rows such as table cells, and the default size in forms and settings.

  • Don’t

    Don't mark a switch invalid. It has no wrong value, and a failed save is an error of the request, so put it in the message.

  • Don’t

    Don't use a Switch to choose between two named options such as Monthly and Yearly. That is a choice, not on or off, so use a Radio Group.

  • Don’t

    Don't ask people to press a Save button after a Switch. A switch that waits for a button is a Checkbox.

API reference

Switch wraps the Base UI switch and takes the props below plus every native attribute, with aria props reaching the track. SwitchItemCell is the table cell that pairs a switch with its text.

The track, with the switch role: 32 by 18 px by default, 24 by 14 px small. Grey when off, brand, neutral or muted when on, with a hit area that reaches 12 px sideways and 8 px up and down.

PropTypeDefaultDescription
checkedboolean—Whether the switch is on. Pass it together with to control the switch; use to let the switch keep the value.
defaultCheckedbooleanfalseWhether the switch starts on, when the switch keeps its own value.
onCheckedChange(checked: boolean, eventDetails) => void—Called when the switch is turned on or off, with the new value as a boolean.
size"sm" | "default""default" is 32 by 18 px, for forms and settings. is 24 by 14 px, for dense rows such as table cells.
appearance"neutral" | "brand" | "muted""brand"The colour of the track while it is on: , (the inverse surface, black in light mode and white in dark mode) or (quiet grey).
savingbooleanfalseA save is running: the knob shows a spinner, the switch is and ignores clicks and keys until you clear it.
disabledbooleanfalseThe switch ignores clicks and keys, is dimmed to 40 % and is skipped by Tab. Dim the label yourself.
readOnlybooleanfalseThe switch keeps its value and cannot be turned on or off. It is announced as read-only.
requiredbooleanfalseThe switch must be on before a form that holds it can be sent. It does not draw anything by itself.
idstring—The id of the hidden input. Point the of the at it.
namestring—The name of the field when a form is sent.
valuestring—The value sent with the form when the switch is on. The default is .
uncheckedValuestring—The value sent with the form when the switch is off. By default an off switch sends nothing, like a native checkbox.
formstring—The id of the form that owns the hidden input, for a switch that is rendered outside the form.
inputRefRef<HTMLInputElement>—A ref to the hidden . The component also copies and onto it.
nativeButtonbooleanfalseSet it to when swaps the element for a native ; the then goes on that element.
renderReactElement | (props, state) => ReactElement—Replaces the element of the track with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the switch's own. A string, or a function of the state. Use it for spacing such as , not to recolour the track.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the track, an object or a function of the state.

A table cell that puts a Switch and its text in one label, so the text also toggles it.

PropTypeDefaultDescription
checkedboolean—Whether the switch in the cell is on.
onCheckedChange(checked: boolean) => void—Called when the switch in the cell is turned on or off.
childrenReactNode—The text next to the switch. It is inside the same , so a click on it toggles the switch.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("switch")
Installnpx wunderui-cli add switch

The full library index for assistants is at /llms.txt.