---
name: switch-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Switch for
boolean settings using Zag.js switch behavior, hidden input, label children,
checked/defaultChecked, validation status, help text, required, disabled, and
read-only state.
metadata:
component_version: "1.4.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/switch"
contributor_sources: "libs/ui/src/molecules/switch.tsx libs/ui/src/tokens/components/molecules/_switch.css libs/ui/stories/molecules/switch.stories.tsx libs/ui/src/molecules/switch.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Switch Usage
Use Switch for immediate boolean settings. Use Checkbox for terms, multi-select
lists, or non-immediate boolean form choices.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Switch`.
**Use it when**
- Settings that take effect immediately (and confirm with a toast): notifications, feature toggles, visibility.
**Use something else when**
| Need | Use instead |
| --- | --- |
| A choice saved with a form's submit | FormCheckbox |
| Agreements and consent | FormCheckbox |
| More than two states | RadioGroup / Select |
**Do**
- Label the setting, not the state (`Email notifications`), and describe the effect in `helpText`.
- Apply on change; on failure revert the switch and show an error toast with `Try again`.
- Keep switches and explicitly-saved fields in separate groups (Settings story rule).
**Don't**
- Put switches in a form that also needs `Save changes` — users can't tell what is already saved.
- Use `On/Off` text inside the label.
**Copy and states**
- Confirmation toast: `Email notifications turned on`.
**Behaviour (from the UX spec)**
- The label names the feature and never changes with the state; on/off stays readable without colour.
- On is not saved: the switch shows the value, the app confirms the write. A failed save reverts the switch (toast with `Try again`), never leaves it looking saved.
- Use `readOnly` (focusable, submitted, can't toggle) for settings the user may see but not change; `disabled` only for a findable reason.
**Figma → code**
| Figma | Code |
| --- | --- |
| `state=checked` / `disabled-checked` | `checked` (+ `disabled`) |
| `state=invalid` | `validateStatus="error"` |
| `state=focus` | not a prop (browser focus) |
| no size axis, no read-only state | `size="sm" \| "md" \| "lg"`, `readOnly` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Switch → UX guidelines*.
## Setup
```tsx
Marketing emails
```
Supported props:
```text
checked/defaultChecked, onCheckedChange
name, value, required, disabled, readOnly, dir
validateStatus: default | error | success | warning
helpText, showHelpTextIcon
requiredLabel: screen-reader text for the required state; pass a translation, "" omits it (default "(required)")
```
## Core Patterns
### Controlled proposals and native reset
A rejected `onCheckedChange` proposal does not change native submission or
validity. Native reset restores the initial uncontrolled default after the
browser reset action, including imperative `form.reset()` while focused.
Canceled resets do not change state or emit value callbacks. Controlled parents
retain ownership: reset silently re-syncs the native input to their checked value.
A click on the input or label, Space, and a scripted `input.click()` each toggle
once and call `onCheckedChange` inside that click, so the native checked state
and FormData are current in the same tick.
The label shrinks and safely wraps long/localized words without shrinking the
track. Enabled unchecked and invalid thumbs have a contrasting state-aware fill.
### Sizes, semantics and read-only values
Use `size="sm" | "md" | "lg"` (default `md`) to scale the track, label and feedback.
The native input has `role="switch"` and reflects `aria-checked`; `dir="rtl"`
mirrors the thumb travel inside the track. `readOnly` preserves focus and form
submission but prevents pointer and Space changes; disabled takes priority.
`aria-describedby` merges caller IDs with inline guidance. Errors set
`aria-invalid` and `aria-errormessage` on the input. Validation always keeps its
status icon; `showHelpTextIcon` only changes optional neutral-help icons.
### Use for settings
Feature toggles, notification preferences, and visibility toggles fit Switch.
### Use children as label
The component renders Label and hidden input internally.
### Use validateStatus for invalid state
Do not style invalid switch state manually.
## Native input ref and cancellation-safe forms
`ref?: Ref` targets the focusable native input with
`role="switch"`, not the track/thumb/label. `inputProps` accepts native
focus/blur/key/change observers, input ARIA and external `form`; top-level
`checked`, `defaultChecked`, `disabled`, `readOnly`, `required`, `name`, `value`
and `id` remain component-owned. Do not use `inputProps` to replace the input
type or value ownership. Descriptions merge with help text. Consumer event
handlers run before machine handlers and respect `preventDefault()`.
```tsx
import { useRef, useState } from "react"
import { Switch } from "@techsio/ui-kit/molecules/switch"
function Notifications() {
const input = useRef(null)
const [enabled, setEnabled] = useState(false)
return
Enable notifications
}
```
Uncontrolled reset restores its initial default only after native/React reset
cancellation has settled. Canceled resets do not change the value or emit a
value callback. The actual native input owner is followed through external-form
ID changes and reparenting; listeners/pending work are disposed on unmount.
Controlled `checked` remains parent-owned even when a proposal is rejected;
applications must explicitly update it when they want a reset. Do not reset by
activating the input or moving focus. Native nested-fieldset disabling and
first-legend exceptions apply; read-only is still focusable and submitted.
Object refs and React 19 callback-ref cleanup are supported.
## Common Mistakes
### HIGH Checkbox for setting toggle
Wrong:
```tsx
Enable notifications
```
Correct:
```tsx
Enable notifications
```
Source: libs/ui/src/molecules/switch.tsx
### HIGH Wrong callback
Wrong:
```tsx
setEnabled(e.target.checked)} />
```
Correct:
```tsx
```
Source: https://zagjs.com/components/react/switch
### HIGH Inline state styling
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/tokens/components/molecules/_switch.css
## Validation Commands
```sh
rg -n "]*onChange=|]*className=.*(bg-|text-|data-\\[state|rounded-)" apps
rg -n "]*validateStatus=\"(danger|invalid)\"" apps
```
## Silent native form reset
Native reset calls no value-change callbacks and dispatches no native `input`
or `change` events, in controlled or uncontrolled usage. Uncontrolled controls
silently restore their default; controlled controls
keep the latest parent value and re-sync visible/accessibility/native submission
state to it. Handle the form's `onReset` to intentionally change parent state.
Canceled resets leave every channel unchanged. Reset does not synthesize events
or move focus; the first real user edit afterward emits exactly one normal
callback, including when the same value was entered before reset.