Switch

Free · MIT

A setting that is on or off. It is off until the person turns it on or the app says so with checked or defaultChecked. Space or Enter flips it. Pair it with a Label. To lock it, wrap it in Locked with a reason: it stays focusable, says why, and doesn't flip. Use a switch for a setting that takes effect at once; a choice the person confirms belongs in a Checkbox or RadioGroup with a button.

After each flip the person makes, the thumb carries data-turned="a" or "b" (the two alternate, so a drawing on it plays again on every flip). It isn't there until the person's first flip, and it goes when the app changes checked by itself, so a drawing never plays for a change the person didn't make. Nothing in the free kit draws it; the Pro motion-drawings item's --cd-draw-switch does.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0 and 2.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

Open the starter in StackBlitz

Opens the free starter app in StackBlitz, in your browser, on stackblitz.com. Switch isn’t added for you: run npx candor-ui add switch in its terminal. The starter’s agent needs an Anthropic API key to chat; without one it shows the components only.

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/switch

Brings in: motion, tokens, utils · npm: @base-ui/react@^1.9.0

Usage

TSX · The example above

"use client"

import * as React from "react"
import { Switch } from "@/components/candor/ui/switch"
import { Label } from "@/components/candor/ui/label"

export default function Example() {
  // The setting is off until the person turns it on.
  const [on, setOn] = React.useState(false)
  return (
    <div className="flex items-center gap-2.5">
      <Switch id="notify" checked={on} onCheckedChange={setOn} />
      <Label htmlFor="notify">{on ? "Notifications are on" : "Notifications are off"}</Label>
    </div>
  )
}

<Switch>

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes, merged with Candor's.

Also takes the props of Omit<SwitchPrimitive.Root.Props, "className">.

Motion

Moment	Family	What it does
thumb	move	The thumb slides to the other end when the state changes, over the move family's 200 ms. It follows the reading direction, so it slides the other way in right-to-left text.

Set with --cd-motion-switch-<moment>-* in your brand file; the families are in the design reference.