Switch

A toggle for an immediate on/off setting — like enabling a feature or flipping a preference. Reach for a Switch when the change takes effect right away; use a Checkbox when the choice is part of a form the user submits later.

Bind its state with v-model. Like the other controls it's label-less: pair it with a Label (matching for/id), or — when there's no visible label — give it an ariaLabel so it still has an accessible name.

Usage

Standalone, with an ariaLabel for accessibility since there's no visible text.

BasicA standalone switch with an aria-label.

<script setup lang="ts">
import { ref } from "vue";
import { Switch } from "@dlbcodes/ui";

const on = ref(false);
</script>

<template>
    <Switch v-model="on" aria-label="Toggle setting" />
</template>

With a label

Pair it with a Label via for/id. Clicking the label toggles the switch.

With LabelSwitch paired with a label.

<script setup lang="ts">
import { ref } from "vue";
import { Switch, Label } from "@dlbcodes/ui";

const enabled = ref(true);
</script>

<template>
    <div class="flex items-center gap-2">
        <Switch id="airplane" v-model="enabled" />
        <Label for="airplane">Airplane mode</Label>
    </div>
</template>

States

On, off, and disabled. The on state is filled with the theme's --primary color, and a disabled switch is dimmed.

StatesOn, off, disabled.

<script setup lang="ts">
import { ref } from "vue";
import { Switch, Label } from "@dlbcodes/ui";

const a = ref(true);
const b = ref(false);
const c = ref(true);
</script>

<template>
    <div class="flex flex-col gap-3">
        <div class="flex items-center gap-2">
            <Switch id="sw-on" v-model="a" />
            <Label for="sw-on">On</Label>
        </div>
        <div class="flex items-center gap-2">
            <Switch id="sw-off" v-model="b" />
            <Label for="sw-off">Off</Label>
        </div>
        <div class="flex items-center gap-2">
            <Switch id="sw-dis" v-model="c" disabled />
            <Label for="sw-dis">Disabled</Label>
        </div>
    </div>
</template>

Appearance

The off track is the theme's --input color, the on track is --primary, and the thumb is --background, so a switch follows your theme, including dark mode. It is always fully rounded regardless of --radius, and the thumb moves the right way in right-to-left layouts. Keyboard focus shows a ring in the --ring color. See Theming.

Props

Prop	Type	Default	Description
modelValue	boolean	—	The on/off state. Use with v-model. Required.
id	string	—	The control's id, for pairing with a Label's for. Provided automatically inside a Field; otherwise generated. Set it yourself to target it from a Label.
disabled	boolean	false	Disables the switch. Inherited from a surrounding Field.
ariaLabel	string	—	Accessible name when there's no associated Label. Set this or pair with a Label.
class	string	—	Classes merged onto the track.

Events: update:modelValue (checked: boolean), emitted when the user toggles the switch.

Accessibility

• Renders a real <input type="checkbox"> with role="switch" and aria-checked, so assistive tech announces it as an on/off switch (not a plain checkbox) and it toggles with the keyboard.
• A switch must have an accessible name: either pair it with a Label (for/id) or set ariaLabel. A switch with neither is unlabelled and inaccessible.
• disabled sets the matching state on the underlying input.

TIP

Inside a Field, the switch inherits id and disabled from the field context. See Field for the full label → control → description pattern.