Switch

Turns a setting on or off immediately.

Public profile

switch-basic-demo.tsx

"use client";import { Switch } from "@/components/vip-ui/switch";export function SwitchBasicDemo() {  return <Switch defaultSelected>Public profile</Switch>;}

Installation

CLI

Manual

The CLI adds the files, packages, theme variables, and Tailwind plugin that this component uses. Before you run it, set up your project.

npm

yarn

pnpm

bun

pnpm dlx shadcn@latest add https://vip-ui.dev/r/vip-switch.json

Composition

SwitchField
Owns the on and off state and validation.
- SwitchButton
  Its text becomes the accessible name.
  - SwitchLabel
  - SwitchControl
    Put it before SwitchLabel to show the control first.
    - SwitchThumb
- SwitchDescription
- SwitchError

Switch Renders all of these parts from children, description, and errorMessage. Use the parts only for a custom layout.

Description

Public profileOthers can find your profile.

switch-description-demo.tsx

"use client";import { Switch } from "@/components/vip-ui/switch";export function SwitchDescriptionDemo() {  return (    <Switch description="Others can find your profile." className="max-w-sm">      Public profile    </Switch>  );}

Disabled

Security alerts

Beta features

switch-disabled-demo.tsx

"use client";import { Switch } from "@/components/vip-ui/switch";export function SwitchDisabledDemo() {  return (    <div className="grid w-full max-w-sm">      <Switch isDisabled defaultSelected>        Security alerts      </Switch>      <Switch isDisabled>Beta features</Switch>    </div>  );}

Control first

Put SwitchControl before SwitchLabel.

AutosaveSave changes as you type.

switch-control-first-demo.tsx

"use client";import {  SwitchButton,  SwitchControl,  SwitchDescription,  SwitchField,  SwitchLabel,  SwitchThumb,} from "@/components/vip-ui/switch";export function SwitchControlFirstDemo() {  return (    <SwitchField defaultSelected className="max-w-sm">      <SwitchButton>        <SwitchControl>          <SwitchThumb />        </SwitchControl>        <SwitchLabel>Autosave</SwitchLabel>      </SwitchButton>      <SwitchDescription>Save changes as you type.</SwitchDescription>    </SwitchField>  );}

Custom layout

Keep SwitchDescription outside SwitchButton so it is read as a description. Also install Badge.

Public profileOthers can find your profile.

Show activityNewShow recent work on your profile.

switch-demo.tsx

"use client";import { Badge } from "@/components/vip-ui/badge";import {  SwitchButton,  SwitchControl,  SwitchDescription,  SwitchField,  SwitchLabel,  SwitchThumb,} from "@/components/vip-ui/switch";const settings = [  {    id: "profile",    label: "Public profile",    description: "Others can find your profile.",    isNew: false,    on: true,  },  {    id: "activity",    label: "Show activity",    description: "Show recent work on your profile.",    isNew: true,    on: false,  },];export function SwitchDemo() {  return (    <div className="w-full max-w-sm divide-y divide-border rounded-xl border border-border bg-card px-4 shadow-[var(--shadow-card)]">      {settings.map((setting) => (        <SwitchField          key={setting.id}          defaultSelected={setting.on}          className="w-full py-3"        >          <SwitchButton>            <SwitchLabel className="flex flex-wrap items-center gap-2">              {setting.label}              {setting.isNew && (                <Badge variant="accent" className="min-h-5 py-0">                  New                </Badge>              )}            </SwitchLabel>            <SwitchControl>              <SwitchThumb />            </SwitchControl>          </SwitchButton>          <SwitchDescription>{setting.description}</SwitchDescription>        </SwitchField>      ))}    </div>  );}

API reference

vip/ui adds or changes the props below. For all other props, see React Aria Switch (opens in a new tab).

children: ReactNode: The label. Without it, pass aria-label so the switch has a name.
description: ReactNode: Help text below the label. Linked with aria-describedby, so it is not part of the name.
errorMessage: string | ((validation: ValidationResult) => string): Shown below the label when isRequired, validate, or isInvalid makes the switch invalid. Without it, the browser validation message shows.
checked: boolean: Alias for isSelected.
defaultChecked: boolean: Alias for defaultSelected.
onCheckedChange: (checked: boolean) => void: Alias for onChange. Both run when both are set.