Switch
A toggle control for binary on/off settings that does not require additional confirmation.
Installation
The component is exported from @by/experience-system. Add the package with your package manager:
pnpm add @by/experience-systemIn this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.
Composition
Use a single Switch with an external Label (or Field) for naming. The thumb is rendered inside the root and is not a separate import:
Switch
└── SwitchPrimitive.Thumb (internal)The experience system composes Radix Switch.Root and Switch.Thumb; consumers render Switch only.
Usage
import { Switch } from '@by/experience-system';Switch is a client component ('use client'). Use it inside a Client Component or a dynamic import when using the Next.js App Router.
<Switch id="notifications" />Pair with Label htmlFor="notifications" (or Field) so the control has an accessible name.
Examples
Overview
Default md size with a Label.
Sizes
size sm, md, and lg on the track and thumb.
API Reference
Switch wraps Radix Switch (radix-ui Switch.Root and an internal Switch.Thumb). The table below summarizes the Radix Root props exposed on Switch, plus the Experience System size extension. For the full primitive matrix (including inherited button behavior), see Radix Switch and MDN — button.
Switch
| Prop | Type | Default |
|---|---|---|
asChild | boolean | false |
checked | boolean | — |
defaultChecked | boolean | — |
disabled | boolean | — |
required | boolean | — |
name | string | — |
value | string | on (Radix; submitted value when checked in a form) |
onCheckedChange | (checked: boolean) => void | — |
size | sm | md | lg | md (Experience System extension) |
Also inherits standard button attributes where Radix forwards them, except type is managed by the primitive for the switch role.
| Data attribute | Values |
|---|---|
data-slot | switch |
data-state | checked | unchecked |
data-disabled | Present when disabled |
| Data attribute (internal thumb) | Values |
|---|---|
data-slot | switch-thumb |
data-state | checked | unchecked |
data-disabled | Present when disabled |
Accessibility
Use an associated Label or aria-label so the switch has an accessible name. disabled removes pointer and keyboard interaction; required participates in constraint validation when inside a form. See Radix Switch — accessibility.
Keyboard interactions
| Key | Description |
|---|---|
Space | Toggles the switch when focused. |
Enter | Toggles the switch when focused. |
Source in the repo: packages/experience-system/src/components/Switch/Switch.tsx. Agent-oriented contracts: packages/experience-system/src/components/Switch/Switch.instructions.md.