Switch
A switch for instant on/off settings, built on a native
<input type="checkbox" role="switch"> so screen readers announce on/off and the
value participates in forms.
Import
Section titled “Import”<script> import Switch from "@invisible-ui/svelte/Switch.svelte";</script><script setup> import { Switch } from "@invisible-ui/vue";</script>import { Switch } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-switch></ds-switch>| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible, visible label; override with children. |
hideLabel | boolean | false | Visually hide the label while keeping it as the accessible name. The label text is always required. |
checked | boolean | false | On/off state. |
disabled | boolean | false | Disable the control. |
name | string | undefined | undefined | Form field name; the value is submitted under it when on. |
value | string | "on" | Value submitted with the form when on. |
required | boolean | false | Mark the control required for native form validation. |
onOff | boolean | false | Show ON/OFF text inside the track (a wider, labelled variant). |
onText | string | undefined | undefined | Text shown in the track when on / off (only with onOff). |
offText | string | undefined | undefined | |
onCheckedChange | ((c: boolean) => void) | undefined | undefined | Called whenever the value changes. |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible, visible label (required). Override with the default slot for rich content. |
hideLabel | boolean | false | Visually hide the label while keeping it as the accessible name. The label text is always required. |
modelValue | boolean | undefined | v-model value; takes precedence over checked when bound. |
checked | boolean | false | |
disabled | boolean | false | |
name | string | undefined | Form field name; the value is submitted under it when on. |
value | string | "on" | Value submitted with the form when on. Defaults to the native "on". |
required | boolean | false | Mark the control required for native form validation. |
onOff | boolean | false | Show ON/OFF text inside the track (a wider, labelled variant). |
onText | string | undefined | Track text when on / off (only with onOff). Defaults to the catalog's "ON" / "OFF". |
offText | string | undefined | |
onCheckedChange | (checked: boolean) => void | undefined | Called whenever the on/off value changes. |
| Event | Payload |
|---|---|
update:modelValue | checked: boolean |
Slots: default.
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Accessible, visible label (required). Override with children for rich content. |
hideLabel | boolean | false | Visually hide the label while keeping it as the accessible name. The label text is always required. |
checked | boolean | false | |
disabled | boolean | false | |
name | string | — | Form field name — the value is submitted under it when on. |
value | string | "on" | Value submitted with the form when on. Defaults to the native "on". |
required | boolean | false | Mark the control required for native form validation. |
onOff | boolean | false | Show ON/OFF text inside the track (a wider, labelled variant). |
onText | string | — | Track text when on / off (only with onOff). Defaults to the catalog's "ON" / "OFF". |
offText | string | — | |
onCheckedChange | (checked: boolean) => void | — | Called whenever the on/off value changes. |
children | ReactNode | — |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | |
hide-label | yes | |
checked | yes | |
disabled | yes | |
name | yes | |
value | yes | |
required | yes | |
on-off | yes | text-in-track variant |
on-text | yes | |
off-text | yes | |
description | yes | |
error | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: checked (boolean).
Emits: bubbling change CustomEvent with detail.checked.
Accessibility
Section titled “Accessibility”- Native
<input type="checkbox" role="switch">: the browser provides Space activation, focus and form participation, and screen readers announce “on”/“off”. - The thumb moves along the inline axis, so in right-to-left text it stays on the track and sits at the end edge, the left one, when on.
- A
labelis required; the native input is wrapped in a<label>, so the visible text names the control and clicking it toggles the switch.
Example
Section titled “Example”<Switch label="Wi-Fi" checked onCheckedChange={(on) => setWifi(on)} />Themeable via --ds-switch-*.