--- 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.