Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
switch · base base · style base-lyraOpen under the product theme

A 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.

Theme
Density
Text
Status
Accent theme
Accent
switch-a-setting-that-applies-now · base base · style base-lyraOpen under the product theme
switch-a-setting-that-applies-now.tsx
"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.

Theme
Density
Text
Status
Accent theme
Accent
switch-with-a-description · base base · style base-lyraOpen under the product theme
switch-with-a-description.tsx
"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-sheet instead.
  • The value is proposed now and submitted later with a form.Use checkbox instead.

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 by aria-labelledby, and state rides aria-checked.
  • On and off are carried by thumb position and aria-checked, not the fill alone, and a border-border hairline survives forced-colors: active and 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. Under prefers-reduced-motion: reduce it does not squash and reaches the other side in one frame.
  • It uses only neutral chrome and the accent fill, and pnpm run check:a11y confirms on every commit that no colour literal, px type 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.

KeyActionNotes
TabMoves focus onto the switchA single tab stop. A disabled switch is skipped.
Shift+TabMoves focus back off the switchOne stop in reverse too.
SpaceFlips the switchonCheckedChange fires with the new boolean.
EnterFlips the switchBase UI binds Enter as well as Space.
Arrow keysNothingNothing to move focus between.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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

AttributeConditionValue
data-slotOn the root and every inner partswitch, switch-label, switch-description, switch-control, switch-thumb
data-checked / data-uncheckedOn the control and the thumb, one or the otherPresent with no value; reflects checked
data-disabledOn the control while disabledPresent with no value