ui/components/switch

Switch

Terminal-styled binary toggle switch. Uses role="switch" with checked/defaultChecked/onChange(boolean) pattern and a hidden native checkbox for form submission.

Preview

tsx

1 import { Switch } from "@/components/ui/switch";2 3 export default function SwitchDefault() {4   return (5     <Switch6       defaultChecked7       label="Enable notifications"8       description="Delivered when a review finishes."9     />10   );11 }12

Installation

$pnpm exec dgadd add ui/switch

[Installs to]src/components/ui/switch[Item]ui/switch

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx

1 import { Switch } from "@/components/ui/switch";2 3 export default function SwitchDefault() {4   return (5     <Switch6       defaultChecked7       label="Enable notifications"8       description="Delivered when a review finishes."9     />10   );11 }12

Examples

Sizes and States

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Switch, type SwitchSize } from "@/components/ui/switch";5 6 const states = [7   { label: "unchecked", checked: false, disabled: false },8   { label: "checked", checked: true, disabled: false },9   { label: "disabled", checked: false, disabled: true },10   { label: "disabled checked", checked: true, disabled: true },11 ];12 13 function SwitchCell({ size, state }: { size: SwitchSize; state: (typeof states)[number] }) {14   const [checked, setChecked] = useState(state.checked);15   // Enabled rows can be toggled, so their caption and accessible name follow the16   // live value; disabled rows never move and keep their sample caption.17   const liveCaption = checked ? "checked" : "unchecked";18   const caption = state.disabled ? state.label : liveCaption;19 20   return (21     <div className="flex flex-col items-center gap-1.5">22       <Switch23         size={size}24         checked={checked}25         onChange={setChecked}26         disabled={state.disabled}27         aria-label={`${size} ${caption}`}28       />29       <span className="text-2xs font-mono text-muted-foreground">{caption}</span>30     </div>31   );32 }33 34 function SwitchRow({ size }: { size: SwitchSize }) {35   return (36     <div className="flex flex-col gap-2">37       <div className="text-xs text-muted-foreground uppercase font-bold">size="{size}"</div>38       <div className="flex flex-wrap items-start gap-6">39         {states.map((state) => (40           <SwitchCell key={state.label} size={size} state={state} />41         ))}42       </div>43     </div>44   );45 }46 47 export default function SwitchStates() {48   return (49     <div className="flex flex-col gap-6">50       <SwitchRow size="sm" />51       <SwitchRow size="md" />52     </div>53   );54 }55

Controlled

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Switch } from "@/components/ui/switch";5 6 export default function SwitchControlled() {7   const [enabled, setEnabled] = useState(true);8 9   return (10     <Switch11       checked={enabled}12       onChange={setEnabled}13       label="Review notifications"14       description={enabled ? "Delivered when a review finishes." : "No notifications are sent."}15     />16   );17 }18

API Reference

Switch

Name	Type	Default	Description
checked	boolean	—	Controlled checked state.
defaultChecked	boolean	false	Initial checked state for uncontrolled usage.
onChange	(checked: boolean) => void	—	Called when the boolean checked state changes.
value	string	"on"	Hidden native input value used for form submission.
name	string	—	Hidden native input name used for form submission.
form	string	—	ID of the form that owns the switch and hidden native input, including when rendered outside that form.
required	boolean	false	Marks the hidden native checkbox as required.
disabled	boolean	false	Disables the switch and hidden input.
label	ReactNode	—	Visible label rendered beside the track. Wires aria-labelledby and makes the whole row a tap target.
description	ReactNode	—	Visible description under the label, wired with aria-describedby.
size	"sm" \| "md"	"md"	Switch size token.
aria-label	string	—	Accessible name for the switch when no visible label labels it.
aria-labelledby	string	—	ID reference for visible text that labels the switch.
aria-describedby	string	—	ID reference for helper or error text describing the switch.
aria-invalid	boolean \| 'true' \| 'false' \| 'grammar' \| 'spelling'	—	Invalid state override. Field.Control also forwards its invalid state to this prop.

Data attributes

Attribute	Applies to	Values	Description
data-state	Switch	"checked" \| "unchecked"	Reflects the checked state for track and thumb styling.
data-slot	Switch row	"switch-row"	Present on the row wrapper rendered when label or description is set.
data-disabled	Switch	present when disabled	Marks the disabled state for styling hooks.

Accessibility

Keyboard Navigation

Switch renders a native button with role=switch, so keyboard activation follows button semantics.

Key	Action
Space	Toggles the checked state when the switch is focused.
Enter	Toggles the checked state when the switch is focused.

Controlled toggle

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Switch } from "@/components/ui/switch";5 6 export default function SwitchControlled() {7   const [enabled, setEnabled] = useState(true);8 9   return (10     <Switch11       checked={enabled}12       onChange={setEnabled}13       label="Review notifications"14       description={enabled ? "Delivered when a review finishes." : "No notifications are sent."}15     />16   );17 }18

Notes

State Glyph

The thumb renders a binary glyph — "1" when checked, "0" when unchecked — so the on/off state stays readable without relying on track inversion or thumb position. The glyph is aria-hidden; role="switch" plus aria-checked carries the state for assistive technology.

Labelled Row

Pass label (and optionally description) to render the same row grammar Checkbox and Radio use: track on the left, label on the right, one shared gap and one shared 44px coarse-pointer height. The label is wired as the accessible name through aria-labelledby, the description through aria-describedby, and clicking either forwards to the control. An explicit aria-label still wins. With neither prop the render is unchanged, so hand-rolled rows keep working.

Disabled Treatment

A disabled switch dashes its track border and resolves the thumb to the recessed surface with a muted digit — the same disabled grammar Input and Textarea use. It is not an opacity fade: forced-colors mode drops opacity but keeps border-style, so the state stays visible in high-contrast themes.

Form Submission

Switch renders a hidden native checkbox when name or required is set. The value prop controls the form-submission string (default "on"). Pass form to associate both the switch and its form mirror with a remote form.

Source

Install via CLI: pnpm exec dgadd add ui/switch. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Switch

Installation

Usage

Examples

Sizes and States

Controlled

API Reference

Switch

Data attributes

Accessibility

Keyboard Navigation

Controlled toggle

Notes

State Glyph

Labelled Row

Disabled Treatment

Form Submission

Source

View component source (17 files)