Switch React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import Switch from @/components/ui/switch.

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

async function saveSetting(key: string, on: boolean) {
  const res = await fetch("/api/settings", { method: "PATCH", body: JSON.stringify({ [key]: on }) })
  if (!res.ok) throw new Error("save failed")
}

export function NotificationSettings() {
  const [messages, setMessages] = useState(true)

  return (
    <div className="flex flex-col divide-y divide-foreground/10 rounded-2xl bg-surface shadow-raised">
      <Switch
        label="New messages"
        description="When someone writes to you about a listing"
        labelPosition="start"
        checked={messages}
        onCheckedChange={setMessages}
        classNames={{ field: "min-h-14 px-4 py-3" }}
      />
      <Switch
        label="Price offers"
        labelPosition="start"
        defaultChecked
        errorText="Could not save. Try again."
        onCheckedChange={(on) => saveSetting("offers", on)}
        classNames={{ field: "min-h-14 px-4 py-3", error: "px-4 pb-3" }}
      />
    </div>
  )
}

Props

• labeldefault ""
  ReactNode

  Text beside the track. The whole row is one <label>, so clicking the text, the description or the empty space toggles it. It names the switch through aria-labelledby. Leave it empty for a bare switch (then pass aria-label).

• descriptiondefault ""
  ReactNode

  A second line under the label, in the muted caption style. It stays out of the switch's name and is linked with aria-describedby, so screen readers read it after the label and the state.

• errordefault ""
  ReactNode

  A message under the row, lined up with the label, that slides in and marks the switch invalid (red ring, aria-invalid). "", false and null are no error; true only marks it invalid.

• requireddefault false
  boolean

  A red mark after the label (hidden from screen readers) and required on the switch, so a native form will not submit while it is off.

• invaliddefault false
  boolean

  The red ring and aria-invalid without a message, for forms that show errors elsewhere.

• disableddefault false
  boolean

  Dims the row to 50% and blocks every input. A disabled Field or FieldGroup around it disables it too.

• readOnlydefault false
  boolean

  Shows the value but ignores clicks, keys and drags, with no hover tint and aria-readonly. It stays focusable, so it is still read out.

• defaultCheckeddefault false
  boolean

  The starting value while uncontrolled. Pass checked and onCheckedChange to control it.

• loadingdefault false
  boolean

  A spinner turns inside the thumb and clicks, keys and drags are ignored, with aria-busy. For a save you track yourself; an async onCheckedChange does the same on its own.

• errorTextdefault "Could not save. Try again."
  ReactNode

  Shown under the row when an async onCheckedChange rejects, and announced. It clears on the next change. Press Simulate an error in the playground to see it.

• sizedefault "md"
  "sm" | "md" | "lg"

  Track 32x18 / 40x24 / 48x28px with a 14 / 20 / 24px thumb, label 13 / 14 / 15px. Rows grow to 44px on touch screens; the track keeps its size.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The track color while on. neutral is black in light mode and white in dark mode, where the thumb turns dark so it still stands out.

• colordefault ""
  string

  Any CSS color for the track while on. Replaces the tone; the thumb turns black or white by the color's lightness. Leave empty to use the tone.

• variantdefault "default"
  "default" | "card"

  card turns the row into a soft-filled tile (the checkbox card look) with the switch at the top end; it takes a ring in the tone while on and dips slightly when pressed. Pair it with icon.

• iconsdefault false
  boolean

  A check inside the thumb while on and an x while off, swapping with a crossfade and a small turn. They stay undistorted while the thumb stretches.

• labelPositiondefault "end"
  "end" | "start"

  end: the switch first, the text after it. start: the text first and the switch at the end of a full-width row, like an iOS settings list. Cards always put the switch at the end.

• checked
  boolean

  The controlled value. With an async onCheckedChange the switch shows the value being saved until the promise settles, then follows checked again, so set checked after the save succeeds (or revert it yourself when it fails) for the rollback to show.

• onCheckedChange
  (checked: boolean) => (void | Promise<unknown>)

  Called with the new value on every click, key or drag. Return a promise to save first: the switch flips at once, spins, ignores input until it settles, and a rejection flips it back, shakes the row and shows errorText. A late result after unmount is ignored.

• checkedIcon
  ReactNode

  A custom icon inside the thumb while on, like a Moon. Unsized svgs follow the size (10 / 12 / 14px) and take the tone color.

• uncheckedIcon
  ReactNode

  A custom icon inside the thumb while off, like a Sun.

• icon
  ReactNode

  Cards: the leading icon tile, which takes the tone's soft color while on. Rows: an icon, thumbnail or avatar before the text, centered on the row.

• namedefault ""
  string

  Form field name. Inside a <form> Radix renders a hidden checkbox that submits value while the switch is on (nothing while off), and a form reset returns it to defaultChecked. The demo prints what the form would submit.

• valuedefault "on"
  string

  What the form submits while the switch is on.

• id
  string

  The switch's id. Inside a Field it reuses the Field's, so the Field's label points at it.

• classNames
  Partial<Record<"field" | "track" | "thumb" | "icon" | "content" | "label" | "description" | "error", string>>

  Extra classes for the parts: the row or card, the track, the thumb, the icon layer, the text column, the label, the description and the error.

• className
  string

  Classes for the outermost element: the wrapper around the row and its message, or the track itself when the switch has no text. Override the tone vars here, e.g. [--tone:var(--success)].

• ref
  RefObject<HTMLButtonElement | null> or (node) => void

  The track: the Radix switch <button role="switch">, which also receives every other prop.

FAQ

Used in

More React input components