Components
Switch
A labelled on-or-off control that commits the moment it is flipped, for a single setting rather than a form value submitted later.
Usage
pnpm dlx shadcn@latest add @opsinjs/switch
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Switch } from "@/components/ui/switch"<Switch
label="Larger text"
checked={largerText}
onCheckedChange={setLargerText}
/>Examples
switch · base base · style base-lyraOpen under the product themeA setting that applies now
checked and onCheckedChange commit "Larger text" on the flip, not on a later
submit. No helper line, because the label alone says what the setting does.
switch-a-setting-that-applies-now · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Switch } from "@/components/ui/switch"
export default function SwitchASettingThatAppliesNow() {
const [on, setOn] = useState(false)
return (
<div className="w-full max-w-sm">
<Switch label="Larger text" checked={on} onCheckedChange={setOn} />
</div>
)
}A setting with a helper line
description adds one sentence under the label saying what turning the switch on
changes. It is read as the description, so the accessible name stays the label.
switch-with-a-description · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Switch } from "@/components/ui/switch"
export default function SwitchWithADescription() {
const [on, setOn] = useState(true)
return (
<div className="w-full max-w-sm">
<Switch
label="Reduce motion"
description="Turns off the sliding and fading animations across the app."
checked={on}
onCheckedChange={setOn}
/>
</div>
)
}When to use it
Use it when
- A single setting, such as a Larger text preference, that takes effect the moment it is flipped.
- A binary state the product commits straight away, with nothing submitted later and the reader free to flip it back.
Do not use it when
- The toggle would record that the reader agreed to something. Consent is a decision with a record.Use
consent-sheetinstead. - The value is proposed now and submitted later with a form.Use
checkboxinstead.
Accessibility
The audit found nothing to change in the source.
role="switch"comes from Base UI's Switch.Root, the accessible name is a visible label span tied byaria-labelledby, and state ridesaria-checked.- On and off are carried by thumb position and
aria-checked, not the fill alone, and aborder-borderhairline survivesforced-colors: activeand a stripped fill. - The 24px AA target floor is met by the track, and the 44pt house floor by the enclosing label row, which toggles the control.
- Focus sits on the track with the house ring. While the row is held the thumb
squashes towards where it will go, and it travels on
spring-snap. Underprefers-reduced-motion: reduceit does not squash and reaches the other side in one frame. - It uses only neutral chrome and the accent fill, and
pnpm run check:a11yconfirms on every commit that no colour literal,pxtype size or banned word appears.
Residual items. No contrast pair has been read yet, so the report below stands in for numbers nobody has produced.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus onto the switch | A single tab stop. A disabled switch is skipped. |
| Shift+Tab | Moves focus back off the switch | One stop in reverse too. |
| Space | Flips the switch | onCheckedChange fires with the new boolean. |
| Enter | Flips the switch | Base UI binds Enter as well as Space. |
| Arrow keys | Nothing | Nothing to move focus between. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from SwitchProps in registry/bases/base/switch.tsx.
checked and onCheckedChange make this a controlled component with no internal
state. label is required: a missing or empty label raises a development warning.
disabled keeps the switch visible and labelled while refusing focus and every
key. className is merged onto the root row and must carry neither colour axis.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and every inner part | switch, switch-label, switch-description, switch-control, switch-thumb |
| data-checked / data-unchecked | On the control and the thumb, one or the other | Present with no value; reflects checked |
| data-disabled | On the control while disabled | Present with no value |