Switch

Purpose

Use Switch for a direct on/off preference whose change is understood as enabling or disabling a setting.

Settings toggles

Email notificationsProduct updatesLocked setting

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

export function Example() {
  return <Label><Switch defaultChecked />Email notifications</Label>;
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/switch

Import

import { Switch } from "@/components/ui/switch";
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Form } from "@/components/ui/form";
import { Label } from "@/components/ui/label";

Need the machine-readable source metadata? View registry JSON.

Usage

Switch is for a setting that can be turned on or off immediately. Use Checkbox for form selection.

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

export function Example() {
  return <Label><Switch defaultChecked />Email notifications</Label>;
}

Examples

States, sizes, field labels, errors, form integration and settings patterns are props and compositions of the same primitive.

States

OffOnDisabledInvalid

<Label><Switch />Off</Label>
<Label><Switch defaultChecked />On</Label>
<Label><Switch defaultChecked disabled />Disabled</Label>
<Label><Switch aria-invalid />Invalid</Label>

Sizes

<Switch aria-label="Small switch" defaultChecked size="sm" />
<Switch aria-label="Default switch" defaultChecked />
<Switch aria-label="Large switch" defaultChecked size="lg" />
<Switch aria-label="Extra large switch" defaultChecked size="xl" />

With label and description

Marketing emails

Allow product update notes in your workspace.

<Field>
  <FieldLabel>
    <Switch defaultChecked />
    Marketing emails
  </FieldLabel>
  <FieldDescription>
    Allow product update notes in your workspace.
  </FieldDescription>
</Field>

Field error

Incident alerts

Notifications must stay on for critical incidents.

<Field>
  <FieldLabel>
    <Switch aria-invalid />
    Incident alerts
  </FieldLabel>
  <FieldDescription>
    Notifications must stay on for critical incidents.
  </FieldDescription>
  <FieldError>This setting is required for admins.</FieldError>
</Field>

Form integration

<Form onSubmit={onSubmit}>
  <Field name="marketing">
    <FieldLabel>
      <Switch defaultChecked name="marketing" value="enabled" />
      Enable marketing emails
    </FieldLabel>
    <FieldDescription>
      This demo submits the switch value without leaving the page.
    </FieldDescription>
  </Field>
  <Button loading={loading} type="submit">Submit</Button>
</Form>

Settings and card patterns

Workspace updatesSend weekly digestAuto dark modeDim UI after local sunset

Enable notificationsYou can enable or disable notifications at any time.

{/* Settings list */}
<div className="grid rounded-lg border border-border">
  <Label className="grid grid-cols-[auto_1fr_auto] items-center gap-3 border-b border-border px-3 py-2 last:border-b-0">
    <BellIcon className="size-4 text-muted-foreground" />
    <span className="grid gap-0.5">
      <span className="font-medium text-sm">Workspace updates</span>
      <span className="text-muted-foreground text-xs">Send weekly digest</span>
    </span>
    <Switch defaultChecked />
  </Label>
</div>

{/* Card pattern */}
<Label className="items-center justify-between rounded-lg border border-border p-3 has-data-checked:border-primary/48 has-data-checked:bg-accent/50">
  <span className="grid gap-1">
    <span>Enable notifications</span>
    <span className="text-muted-foreground text-xs">
      You can enable or disable notifications at any time.
    </span>
  </span>
  <Switch defaultChecked />
</Label>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

Switch accepts controlled checked, uncontrolled defaultChecked, onCheckedChange, disabled, readOnly, required, name, value and Base UI switch props.
size="sm" | "default" | "lg" | "xl" overrides the nearest SiteplaneUIProvider control size.
The native control mirrors checked, disabled and invalid state through Base UI attributes and form participation.
Every size keeps a consistent 2 px inset between track and thumb without changing the outer track dimensions.
Track radius scales with control size through the existing provider-derived radius tokens, and the thumb inherits the same radius, including radius="none".

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

The thumb translates and stretches through the native Siteplane Switch motion contract; hover and press feedback stay inside the primitive.
Reduced motion keeps the checked state immediate and removes non-essential transition.

Accessibility

Pair every Switch with a visible clickable label or provide a precise accessible name.
Use Switch for settings, Checkbox for form agreement or multi-select, and never communicate state by color alone.
Disabled, read-only and invalid state need supporting context when the reason is not obvious.

Implementation Guidance

Use only the documented sizes or provider default.
Keep label and control as one clickable setting row without nesting unrelated actions.
Do not rebuild the switch track or thumb from raw elements.