Switch

StableBase UI

Live preview

Installation

pnpm dlx shadcn@latest add @sc1m/switch

This also merges the token layer and installs src/lib/cn.ts plus @base-ui/react. For the manual route — prerequisites, components.json, and app-level setup — see Installation.

Usage

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

Example

The preview above, with its source. This is the demo module verbatim, so the code and the thing it renders cannot drift apart.

<Switch aria-label="Toggle setting" />

API reference

Each part forwards every prop of its Base UI counterpart; the tables list the ones declared on the part itself. See Base UI's reference for the inherited element props.

PropTypeDefaultDescription

idstring—The id of the hidden input element.

checkedboolean—Whether the switch is currently active.

defaultCheckedbooleanfalseWhether the switch is initially active.

disabledbooleanfalseWhether the component should ignore user interaction.

inputRefReact.Ref<HTMLInputElement>—A ref to access the hidden <input> element.

namestring—Identifies the field when a form is submitted.

formstring—Identifies the form that owns the hidden input.

onCheckedChange((checked: boolean, eventDetails: SwitchRoot.ChangeEventDetails) => void)—Event handler called when the switch is activated or deactivated.

readOnlybooleanfalseWhether the user should be unable to activate or deactivate the switch.

requiredbooleanfalseWhether the user must activate the switch before submitting a form.

valuestring—The value submitted with the form when the switch is on.

uncheckedValuestring—The value submitted with the form when the switch is off.

Accessibility

Behaviour, focus management, and ARIA wiring come from Base UI's Switch — see its reference for the full keyboard map.

Keyboard focus draws a 2px ring in --ring, never removed — only shown on :focus-visible, so a pointer press does not paint one.
Disabled parts mute their contents rather than the element, keeping the focus ring at full strength where the part stays focusable.

Design tokens

The component reads semantic tokens only — no raw colour, radius, or duration appears in its source. Override the token, not the component.

TokenApplied to

--accentSwitch

--line-strongSwitch

--ringSwitch

--shadow-raisedSwitch

--surface-raisedSwitch

Source

src/components/ui/switch/switch.tsx — no next/* imports, so it drops into any React 19 + Tailwind v4 app.

Switch

On this page