Switch

Install

pnpm dlx shadcn@latest add @vegastack/switch

Usage

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

<Switch defaultChecked aria-label="Email notifications" />;

Pair it with Field (horizontal orientation) for an associated, clickable label:

import { Field } from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

<Field label="Email notifications" orientation="horizontal">
  <Switch defaultChecked />
</Field>;

Base UI renders the default switch root as a <span role="switch"> plus a hidden <input>. When your markup needs a sibling <label htmlFor>, render the root as a native button so the id targets the visible interactive element:

<label htmlFor="notifications-switch">Notifications</label>
<Switch
  id="notifications-switch"
  nativeButton
  render={<button type="button" />}
/>

Examples

Sizes

sm (16px), default (20px), and lg (24px) — the track and thumb scale together. The grid shows every size in both the off and on positions, since the thumb-travel geometry (the inset gap at rest vs. when checked) differs per size.

States

On, off, and disabled (in both positions). State is driven by Base UI's data-checked / data-unchecked attributes, so it works controlled (checked + onCheckedChange) or uncontrolled (defaultChecked).

Controlled

Drive the switch from state with checked + onCheckedChange. Use this when the value must stay in sync with other UI or be persisted on change.

const [enabled, setEnabled] = useState(true);

<Switch
  checked={enabled}
  onCheckedChange={setEnabled}
  aria-label="Email notifications"
/>;

Invalid

The switch itself shows no visual invalid treatment — no destructive border and no status dot. It keeps its normal appearance while aria-invalid is set (either directly on a standalone Switch, or automatically when a wrapping <Field error=…> marks the control invalid), and the Field's error copy is the affordance that explains what must be corrected.

Playground

Try every size and the disabled state, then copy the generated JSX.

<Field label="Email notifications" orientation="horizontal">
  <Switch />
</Field>

API Reference

Accessibility

• Renders a <span role="switch"> with a hidden <input> for form submission by default — exposes aria-checked to assistive tech. Use nativeButton render={<button />} for sibling <label htmlFor> patterns.
• Keyboard: Tab to focus, Space / Enter to toggle.
• :focus-visible shows a 2px ring (outline-ring) — never outline: none.
• disabled removes it from the tab order and blocks toggling.
• Always give the switch an accessible name — a <Field> label, or aria-label when standalone.

Do / Don't