◇

Switch

2 parts

A control that toggles between an on and off state, mirroring a physical switch. Renders with role="switch", exposes data-state and data-disabled for styling, and optionally mirrors its value into a hidden form input via name. The value is generic: it defaults to a boolean but can be any pair of truthy/falsy values (strings, numbers, objects compared by identity), and works uncontrolled (defaultValue) or controlled with v-model. Use it for instant settings toggles where the change applies immediately, as opposed to a checkbox that is typically submitted with a form. Pair it with SwitchThumb for the moving part: the thumb reads the switch context and mirrors data-state/data-disabled, enabling data-[state=checked] thumb animations.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  Switch,
  SwitchThumb,
} from '@robonen/primitives/forms/switch';

<Switch>
  <SwitchThumb />
</Switch>

API Reference

Switch

Root

A control that toggles between an on and off state, mirroring a physical switch. Renders with `role="switch"`, exposes `data-state` and `data-disabled` for styling, and optionally mirrors its value into a hidden form input via `name`. The value is generic: it defaults to a boolean but can be any pair of `truthy`/`falsy` values (strings, numbers, objects compared by identity), and works uncontrolled (`defaultValue`) or controlled with `v-model`. Use it for instant settings toggles where the change applies immediately, as opposed to a checkbox that is typically submitted with a form. Pair it with `SwitchThumb` for the moving part: the thumb reads the switch context and mirrors `data-state`/`data-disabled`, enabling `data-[state=checked]` thumb animations.

Prop	Type	Default	Description
`truthy`?	`T`	—	Value representing the "on" state. Defaults to `true`.
`falsy`?	`T`	—	Value representing the "off" state. Defaults to `false`.
`defaultValue`?	`T`	—	Initial uncontrolled value. Defaults to `falsy`.
`disabled`?	`boolean`	—	Prevents toggling and reflects a disabled state to assistive technology.
`required`?	`boolean`	—	Marks the control as required for form submission (sets `aria-required`).
`name`?	`string`	—	Name for the hidden form input. If provided, a hidden input mirrors state.
`id`?	`string`	—	Id of the root element. Anchors an associated `<label for>` and lets the switch derive an accessible name from that label when no explicit `aria-label` is supplied.
`value`?	`string`	—	Explicit string submitted with the form when the switch is on. When omitted the current `truthy`/`falsy` value is serialized automatically, so number, boolean and object pairs round-trip without extra wiring.
`modelValue`?	`T`	—	Two-way bound value (`v-model`).

Emits

Event	Payload
`update:modelValue`	`[value: T]`

SwitchThumb

Thumb

The moving part of a switch. Renders alongside the root and mirrors the root's state through its own `data-state` (`checked`/`unchecked`) and `data-disabled` attributes, so the thumb can be animated with `data-[state=checked]` selectors — the most common switch UI pattern. It holds no state of its own; it reads the switch context provided by the root.

No props or events — renders its element and forwards attributes.