Switch
Switches represent standalone boolean settings that apply immediately, including read-only and invalid states.
Overview and decision boundary
Use Switch for settings that turn something on or off immediately.
Do not use Switch when a separate Save, Apply, Submit, or Confirm action is still required unless delayed behavior is clearly communicated.
Notify collaboratorsCollaborators receive updates as they happen.Automatic updatesThis setting is managed by your workspace.
import { Switch } from "@nerio-ui/ui/client";<Switch defaultChecked label="Notify collaborators" description="Collaborators receive updates as they happen."/>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add switchimport { Switch } from "@nerio-ui/ui/client";Usage
import { Switch } from "@nerio-ui/ui/client";<Switch defaultChecked name="notifyCollaborators" label="Notify collaborators" description="Collaborators receive updates as they happen."/>Variants
| Variant | Use |
|---|---|
Default | Standalone boolean yes/no value. |
Anatomy
| Slot | Purpose |
|---|---|
field | Optional wrapper that groups Switch with its label and description. |
root | Interactive Base UI switch control with checked state. |
thumb | Movable indicator for on and off state. |
label | Optional visible name connected to the control with aria-labelledby. |
description | Optional supporting text connected with aria-describedby. |
States
| State | Behavior |
|---|---|
Off | Setting is disabled. |
On | Setting is enabled. |
Disabled | Setting cannot be changed. |
Read-only | Setting remains visible without accepting changes. |
Invalid | Validation state is exposed through aria-invalid and data-invalid. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- Uses the Base UI Switch primitive for keyboard and checked-state behavior.
- Use Switch for immediate on/off settings, not multi-select form choices.
- Provide a visible label or accessible name with aria-label or aria-labelledby; label automatically connects the visible name.
- Description automatically connects supporting text with aria-describedby, while explicit aria-describedby values are preserved.
- Supports checked, defaultChecked, onCheckedChange, disabled, required, name, value, form, id, and aria-describedby through the Base UI root props.
- Invalid, disabled, and read-only states preserve a visible boundary and semantics.
- Do not use Switch for long-running or destructive actions.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Purpose |
|---|---|
checked / defaultChecked / onCheckedChange | Controlled and uncontrolled Base UI state APIs. |
label | Optional visible name for the switch field row. |
description | Optional supporting text displayed below label and announced as a description. |
name / value / form / required / disabled / readOnly | Native form metadata is preserved. |
invalid | Sets data-invalid and aria-invalid when true. |
className | Extends the switch control, not the optional field wrapper. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | switch installs 5 Tailwind-first source files into the configured components directory. |
Base UI | switch |
Registry dependencies | None. |
Package dependencies | @base-ui/react, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Switch for settings that turn something on or off immediately.
Do / do not
Do
Use for any standalone yes/no value, including preferences, permissions, and form settings.
Do not
Use Switch for selecting several options from a group; use Checkbox for that pattern.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Sizing | --n-switch-height / --n-switch-width / --n-switch-radius | Compact web track with iOS-like proportions. |
Thumb | --n-switch-thumb-size / offset / radius / background | Fixed white thumb across modes with a 2px inset and circular motion. |
Off track | --n-switch-background / --n-switch-background-hover | Neutral inactive state. |
On track | --n-switch-background-checked / --n-switch-background-checked-hover | Theme-aware enabled track with an invariant white thumb. |
Focus | --n-focus-ring | Visible keyboard focus treatment. |