OSwitch

OSwitch renders a native boolean checkbox with a switch presentation.

Usage

Step by step

1. Import OSwitch from the ooko-ui/switch public subpath.
2. Bind its boolean state with v-model and provide the required label.
3. Add native checkbox attributes, guidance, or validation state as needed.

Example

The rendered example and its source come from the same Vue single-file component.

Email notifications

Interactive playground

Change the value, label, guidance, size, and switch states. The preview updates immediately.

Email notifications

You can change this later.

Size smmdLabel Hint Error Disabled Read-only Required Hide label

Props

Prop	Type	Default	Description
modelValue	boolean	false	Current controlled boolean state of the switch.
size	OokoFormControlSize	undefined	Controls the choice control's form-control scale.
label	string	undefined	Visible or visually hidden accessible label.
id	string	undefined	Native input identifier. A hydration-safe identifier is generated when omitted.
name	string	undefined	Native form field name and OForm validation key.
hint	string	undefined	Persistent guidance displayed below the choice control.
error	string	undefined	Controlled validation error displayed below the choice control.
validation	OokoValidationBinding	undefined	Validation binding created by useOokoValidation.
hideLabel	boolean	false	Visually hides the label while preserving its accessible name.
required	boolean	false	Marks the native input as required.
disabled	boolean	false	Disables the native input.
readonly	boolean	false	Prevents changes while keeping the input focusable.

Events

Event	Payload	Description
update:modelValue	boolean	Emits the next boolean state after a native change.

Slots

Slot	Props	Description
default	none	Provides the switch label content.

Related types

Type	Definition
OokoFormControlSize	type OokoFormControlSize = "sm" | "md";

CSS custom properties

Custom property	Default	Description
--o-switch-gap	var(--o-space-2)	Sets the space between the switch and its label.
--o-switch-track-inline-size	var(--o-space-10)	Sets the switch track width.
--o-switch-track-block-size	var(--o-space-5)	Sets the switch track height.
--o-switch-thumb-inset	var(--o-space-0-5)	Sets the switch thumb inset.
--o-switch-focus-width	0.1875rem	Sets the focus outline width.
--o-switch-focus-style	solid	Sets the focus outline style.
--o-switch-focus-offset	0.125rem	Sets the distance between the switch and focus outline.
--o-switch-disabled-opacity	0.5	Sets the opacity of a disabled switch.

Override example

:root {
  --o-switch-track-inline-size: var(--o-space-12);
}

Accessibility

The component keeps native checkbox semantics and a control row that acts as its label, rather than substituting a custom ARIA switch. Clicking the track or text toggles it. Space toggles it, focus is visibly indicated, and disabled behavior uses the native attribute. readonly remains focusable and exposes aria-readonly; it does not change value. Hints and feedback are referenced by aria-describedby, while errors are announced politely. Forced-colors and reduced-motion preferences are respected.

Behavior and edge cases

The controlled model is always boolean and emits the next boolean state. Native attributes and listeners are forwarded to the input; consumer classes and styles apply to the component root. size accepts sm and md, and may be configured through app defaults.