Switch

Airplane mode

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

export default function SwitchDemo() {
  return <Switch defaultSelected>Airplane mode</Switch>;
}

Installation

$ pnpm dlx shadcn@latest add @desyne/switch

The CLI installs dependencies and any other components this one uses.

Usage

tsx

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

tsx

<Switch isSelected={wifi} onChange={setWifi}>
  Wi-Fi
</Switch>

Switches apply immediately

Users expect a switch to take effect the moment it's flipped, like a light switch. If the change only applies after pressing Save or Submit, use a Checkbox instead.

When to use

Switch — a single on/off setting that applies right away: notifications, dark mode, a feature flag.
Checkbox — options confirmed by a submit button, required consent, or many options in a group.
Toggle Button — an on/off state inside a toolbar, like bold or mute.
Radio Group — more than two states, or two states whose labels aren't simply "on" and "off".

Anatomy

tsx

<Switch>      {/* <label> wrapping a hidden <input type="checkbox" role="switch"> */}
  Label       {/* children */}
</Switch>

Part	Renders	Notes
`Switch`	`<label>` + hidden `<input role="switch">`	Root. Carries `data-slot="switch"` and every state attribute.
Track	`<span>`	The pill. Uses `--brand` when on. Sized by `size`.
Thumb	`<span>`	The white knob; slides to the end when on.
Label	children	Next to the track. With `description`, becomes a bold title with secondary text under it.

Examples

Sizes

md is the default. Use sm in dense lists and tables, and lg for a prominent master switch or touch-first layouts.

SmallMediumLarge

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

export default function SwitchSizes() {
  return (
    <div className="flex items-center gap-6">
      <Switch size="sm" defaultSelected>
        Small
      </Switch>
      <Switch size="md" defaultSelected>
        Medium
      </Switch>
      <Switch size="lg" defaultSelected>
        Large
      </Switch>
    </div>
  );
}

With description

description adds secondary text under the label and aligns the track to the first line. Use it to explain what the setting does.

Quiet hoursPause all notifications from 10 PM to 7 AM in your local time zone.

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

export default function SwitchDescription() {
  return (
    <Switch
      className="max-w-xs"
      defaultSelected
      description="Pause all notifications from 10 PM to 7 AM in your local time zone."
    >
      Quiet hours
    </Switch>
  );
}

Label placement

labelPlacement="start" puts the label first and pushes the switch to the far end of its container, which is the usual layout for settings rows.

Label after (end)Label before (start)

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

export default function SwitchLabelPlacement() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-5">
      <Switch defaultSelected>Label after (end)</Switch>
      <Switch labelPlacement="start" defaultSelected>
        Label before (start)
      </Switch>
    </div>
  );
}

States

isDisabled dims the switch and removes it from the tab order. isReadOnly keeps it focusable and announced, but ignores presses, which is useful while a change is saving.

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

export default function SwitchStates() {
  return (
    <div className="grid grid-cols-2 gap-x-8 gap-y-4">
      <Switch>Off</Switch>
      <Switch defaultSelected>On</Switch>
      <Switch isDisabled>Disabled</Switch>
      <Switch isDisabled defaultSelected>
        Disabled on
      </Switch>
      <Switch isReadOnly>Read-only</Switch>
      <Switch isReadOnly defaultSelected>
        Read-only on
      </Switch>
    </div>
  );
}

Controlled

Use isSelected and onChange to own the value. Use defaultSelected when you only need the initial state.

Maintenance mode

Your site is live.

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

export default function SwitchControlled() {
  const [isSelected, setSelected] = useState(false);
  return (
    <div className="flex flex-col items-start gap-3">
      <Switch isSelected={isSelected} onChange={setSelected}>
        Maintenance mode
      </Switch>
      <p className="text-muted-foreground text-sm">
        Your site is{" "}
        <span className="font-medium text-foreground">
          {isSelected ? "showing a maintenance page" : "live"}
        </span>
        .
      </p>
    </div>
  );
}

Without a visible label

When the label lives elsewhere in the layout, point to it with aria-labelledby (and to helper text with aria-describedby). A switch with no label at all needs an aria-label.

Dark mode

Follows your system by default.

import { MoonIcon } from "lucide-react";
import { Switch } from "@/components/ui/switch";

export default function SwitchStandalone() {
  return (
    <div className="flex w-full max-w-xs items-center gap-3 rounded-lg border bg-card p-3">
      <MoonIcon className="size-4 text-muted-foreground" />
      <div className="flex-1">
        <p id="dark-mode-label" className="font-medium text-sm">
          Dark mode
        </p>
        <p id="dark-mode-hint" className="text-muted-foreground text-xs">
          Follows your system by default.
        </p>
      </div>
      <Switch
        aria-labelledby="dark-mode-label"
        aria-describedby="dark-mode-hint"
      />
    </div>
  );
}

Settings list

labelPlacement="start" plus description and some padding turns each switch into a full-width, fully clickable settings row.

Security alertsReceive emails about account activity.Product updatesGet notified about new features.Marketing emailsManaged by your organization.

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

export default function SwitchSettings() {
  return (
    <div className="flex w-full max-w-sm flex-col divide-y rounded-lg border">
      <Switch
        labelPlacement="start"
        className="p-4"
        defaultSelected
        description="Receive emails about account activity."
      >
        Security alerts
      </Switch>
      <Switch
        labelPlacement="start"
        className="p-4"
        description="Get notified about new features."
      >
        Product updates
      </Switch>
      <Switch
        labelPlacement="start"
        className="p-4"
        isDisabled
        description="Managed by your organization."
      >
        Marketing emails
      </Switch>
    </div>
  );
}

Revealing options

Control the switch to show dependent fields only when the setting is on.

Out-of-office replyReply automatically while you're away.

Message

import { useState } from "react";
import { Switch } from "@/components/ui/switch";
import { TextareaField } from "@/components/ui/textarea";

export default function SwitchReveal() {
  const [enabled, setEnabled] = useState(true);
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <Switch
        isSelected={enabled}
        onChange={setEnabled}
        description="Reply automatically while you're away."
      >
        Out-of-office reply
      </Switch>
      {enabled && (
        <TextareaField
          label="Message"
          rows={3}
          defaultValue="I'm away until Monday and will reply when I'm back."
          className="pl-11.5"
        />
      )}
    </div>
  );
}

Because switches apply immediately, persist the change right away. Update optimistically, set isReadOnly while the request is in flight, and roll back with a message if it fails. The status text is in an aria-live region so screen-reader users hear the outcome.

Auto-deploy on push

import { useState } from "react";
import { Spinner } from "@/components/ui/spinner";
import { Switch } from "@/components/ui/switch";

// Stand-in for a real request. Fails one time in four.
const save = (value: boolean) =>
  new Promise<boolean>((resolve, reject) =>
    setTimeout(
      () => (Math.random() < 0.25 ? reject(new Error()) : resolve(value)),
      800,
    ),
  );

export default function SwitchAsync() {
  const [enabled, setEnabled] = useState(true);
  const [status, setStatus] = useState<"idle" | "saving" | "error">("idle");

  const onChange = async (next: boolean) => {
    setEnabled(next); // optimistic
    setStatus("saving");
    try {
      await save(next);
      setStatus("idle");
    } catch {
      setEnabled(!next); // roll back
      setStatus("error");
    }
  };

  return (
    <div className="flex flex-col items-start gap-2">
      <Switch
        isSelected={enabled}
        onChange={onChange}
        isReadOnly={status === "saving"}
      >
        Auto-deploy on push
      </Switch>
      <p
        aria-live="polite"
        className="flex h-4 items-center gap-1.5 text-muted-foreground text-xs"
      >
        {status === "saving" && (
          <>
            <Spinner size="xs" aria-hidden /> Saving…
          </>
        )}
        {status === "error" && (
          <span className="text-destructive">
            Couldn't save. Your change was undone.
          </span>
        )}
      </p>
    </div>
  );
}

Form submission

Give the switch a name and its value ("on" by default) is submitted when it's on. Like a native checkbox, nothing is submitted when it's off, so treat a missing key as false on the server.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Switch } from "@/components/ui/switch";

export default function SwitchForm() {
  const [result, setResult] = useState<string | null>(null);
  return (
    <Form
      className="flex w-full max-w-xs flex-col gap-4"
      onSubmit={(e) => {
        e.preventDefault();
        setResult(
          JSON.stringify(Object.fromEntries(new FormData(e.currentTarget))),
        );
      }}
    >
      <Switch name="public" defaultSelected>
        Public repository
      </Switch>
      <Switch name="issues" value="enabled" defaultSelected>
        Enable issues
      </Switch>
      <Switch name="wiki" value="enabled">
        Enable wiki
      </Switch>
      <Button type="submit" className="self-start">
        Save
      </Button>
      {result && (
        <code className="rounded-md bg-muted px-2 py-1 text-xs">{result}</code>
      )}
    </Form>
  );
}

Switch doesn't support isRequired or validation. For a required "I agree" control, use a Checkbox.

Recipes

Notification settings

A large master switch that disables and clears the category switches under it.

Email notificationsTurn off to pause every email notification.CommentsReplies and mentions on issues you follow.Review requestsWhen someone asks for your review on a pull request.DeploymentsFailed and promoted deployments in your projects.

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

const categories = [
  {
    id: "comments",
    title: "Comments",
    description: "Replies and mentions on issues you follow.",
  },
  {
    id: "reviews",
    title: "Review requests",
    description: "When someone asks for your review on a pull request.",
  },
  {
    id: "deploys",
    title: "Deployments",
    description: "Failed and promoted deployments in your projects.",
  },
];

export default function SwitchRecipeNotifications() {
  const [enabled, setEnabled] = useState(true);
  const [prefs, setPrefs] = useState<Record<string, boolean>>({
    comments: true,
    reviews: true,
    deploys: false,
  });

  return (
    <div className="w-full max-w-md divide-y rounded-xl border bg-card">
      <Switch
        labelPlacement="start"
        size="lg"
        className="p-5"
        isSelected={enabled}
        onChange={setEnabled}
        description="Turn off to pause every email notification."
      >
        Email notifications
      </Switch>
      {categories.map((c) => (
        <Switch
          key={c.id}
          labelPlacement="start"
          className="px-5 py-4"
          isDisabled={!enabled}
          isSelected={enabled && prefs[c.id]}
          onChange={(value) => setPrefs((p) => ({ ...p, [c.id]: value }))}
          description={c.description}
        >
          {c.title}
        </Switch>
      ))}
    </div>
  );
}

Feature flags

Small switches aligned to the end of each row, labelled by the flag name via aria-labelledby, with a Badge for the release stage.

New editorBeta
new-editor · Enabled for 25% of users
AI summariesAlpha
ai-summaries · Internal team only
Usage-based billingGA
usage-billing · Enabled for all users

import { useState } from "react";
import { Badge } from "@/components/ui/badge";
import { Switch } from "@/components/ui/switch";

const flags = [
  {
    key: "new-editor",
    name: "New editor",
    stage: "beta",
    rollout: "Enabled for 25% of users",
  },
  {
    key: "ai-summaries",
    name: "AI summaries",
    stage: "alpha",
    rollout: "Internal team only",
  },
  {
    key: "usage-billing",
    name: "Usage-based billing",
    stage: "ga",
    rollout: "Enabled for all users",
  },
] as const;

const stages = {
  alpha: { label: "Alpha", color: "warning" },
  beta: { label: "Beta", color: "info" },
  ga: { label: "GA", color: "success" },
} as const;

export default function SwitchRecipeFeatureFlags() {
  const [on, setOn] = useState<Record<string, boolean>>({
    "new-editor": true,
    "ai-summaries": false,
    "usage-billing": true,
  });

  return (
    <ul className="w-full max-w-md divide-y rounded-xl border bg-card">
      {flags.map((flag) => (
        <li key={flag.key} className="flex items-center gap-4 px-4 py-3">
          <div className="min-w-0 flex-1">
            <div className="flex items-center gap-2">
              <span id={`flag-${flag.key}`} className="font-medium text-sm">
                {flag.name}
              </span>
              <Badge size="sm" color={stages[flag.stage].color}>
                {stages[flag.stage].label}
              </Badge>
            </div>
            <p className="font-mono text-muted-foreground text-xs">
              {flag.key} · {flag.rollout}
            </p>
          </div>
          <Switch
            size="sm"
            aria-labelledby={`flag-${flag.key}`}
            isSelected={on[flag.key]}
            onChange={(value) => setOn((o) => ({ ...o, [flag.key]: value }))}
          />
        </li>
      ))}
    </ul>
  );
}

Billing period toggle

A switch that flips pricing cards between monthly and yearly billing.

Yearly billing2 months free

Starter

$12 /month

Billed monthly

3 projects
Basic analytics
Email support

Growth

$39 /month

Billed monthly

Unlimited projects
Advanced analytics
Priority support

import { CheckIcon } from "lucide-react";
import { useState } from "react";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Switch } from "@/components/ui/switch";

const tiers = [
  {
    name: "Starter",
    monthly: 12,
    features: ["3 projects", "Basic analytics", "Email support"],
  },
  {
    name: "Growth",
    monthly: 39,
    features: ["Unlimited projects", "Advanced analytics", "Priority support"],
  },
];

export default function SwitchRecipeBillingToggle() {
  const [yearly, setYearly] = useState(false);
  return (
    <div className="flex w-full max-w-lg flex-col items-center gap-5">
      <div className="flex items-center gap-3 text-sm">
        <Switch isSelected={yearly} onChange={setYearly}>
          Yearly billing
        </Switch>
        <Badge color="success" size="sm">
          2 months free
        </Badge>
      </div>
      <div className="grid w-full gap-4 sm:grid-cols-2">
        {tiers.map((tier) => {
          const price = yearly
            ? Math.round((tier.monthly * 10) / 12)
            : tier.monthly;
          return (
            <div
              key={tier.name}
              className="flex flex-col gap-4 rounded-xl border bg-card p-5"
            >
              <div>
                <p className="font-medium text-sm">{tier.name}</p>
                <p className="mt-1">
                  <span className="font-semibold text-3xl tabular-nums">
                    ${price}
                  </span>
                  <span className="text-muted-foreground text-sm"> /month</span>
                </p>
                <p className="text-muted-foreground text-xs">
                  {yearly
                    ? `$${tier.monthly * 10} billed yearly`
                    : "Billed monthly"}
                </p>
              </div>
              <ul className="grid gap-2 text-sm">
                {tier.features.map((f) => (
                  <li key={f} className="flex items-center gap-2">
                    <CheckIcon className="size-4 text-success" /> {f}
                  </li>
                ))}
              </ul>
              <Button variant="outline" className="mt-auto">
                Choose {tier.name}
              </Button>
            </div>
          );
        })}
      </div>
    </div>
  );
}

Accessibility

Renders a native <input type="checkbox" role="switch">, visually hidden inside a <label>, so screen readers announce it as a switch that is on or off, and clicking the label toggles it.
Keep the label constant (e.g. "Wi-Fi"), not "Turn on Wi-Fi" / "Turn off Wi-Fi": the on/off state is announced separately.
A switch without children needs aria-label or aria-labelledby.
description is rendered inside the <label>, so it's read as part of the name. For long help text, render it outside and link it with aria-describedby.
If a change can fail or takes time, announce the outcome in an aria-live region.
The focus ring only appears for keyboard focus (data-focus-visible).

Keyboard

Key	Action
`Tab`	Moves focus to the switch
`Space`	Toggles the switch

Styling

Data attributes

On the Switch root (target the track or thumb with group-data-*/switch:):

Attribute	Present when
`data-selected`	On
`data-hovered`	Hovered with a mouse or pen
`data-pressed`	Being pressed
`data-focused` / `data-focus-visible`	Focused / focused with the keyboard
`data-disabled`	`isDisabled` is true
`data-readonly`	`isReadOnly` is true

Slots

`data-slot`	Element
`switch`	The `<label>` root. Target switches from a parent with `*:data-[slot=switch]:…`

Color

The track uses the --brand theme variable when on. Override it for a one-off color:

tsx

<Switch className="[--brand:var(--color-emerald-600)]">Online</Switch>

Render props

className and children accept a function of the switch state:

tsx

<Switch>{({ isSelected }) => (isSelected ? "Visible to everyone" : "Hidden")}</Switch>

API Reference

Switch

Prop

Type

Also accepts every prop of React Aria's Switch.

Checkbox — for options confirmed with a submit button.
Toggle Button — an on/off button for toolbars.
Radio Group — for more than two states.