<c-switch>
A toggle for a binary setting that takes effect immediately: a native switch control with a label.
Usage
Bind the state with a plain v-model: value is true-value while the
switch is on and false-value while it is off (true and false unless you
map them onto custom values). checked is the same state as a boolean —
setting it sets value, and a checked attribute sets the initial state when
no value is bound.
<c-switch v-model="notifications">Email notifications</c-switch>
When to use
- Turning a setting or mode on/off with immediate effect (no submit step).
When not to use
- A choice that is collected and submitted with a form — use
c-checkbox.
Accessibility
The switch is a native input named by its label. Without a visible label, set aria-label on the element: it names the input, as the other ARIA attributes on the element describe it.
Customization
Restyle via CSS parts from your own stylesheet. The slider part is the
toggle track (its ::before pseudo-element is the handle); the host exposes
the checked custom state, so the track is stylable per state:
c-switch:state(checked)::part(slider) {
background: var(--my-green);
}
c-switch:state(checked)::part(slider)::before {
background: white;
}
For app-wide recolouring prefer the design tokens (--c-primary seed) over
per-component rules.
Examples
<template>
<div class="example-grid">
<c-switch v-model="enabled">Notifications</c-switch>
<p>Value: {{ enabled }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const enabled = ref(false);
</script>
<template>
<c-switch label="Email notifications" required />
</template>
<template>
<div class="example-grid">
<c-switch
:disabled="pending"
:loading="pending"
:value="enabled"
@change="onToggle"
>
Sync to cloud
</c-switch>
<p>{{ pending ? 'Saving…' : `Value: ${enabled}` }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const enabled = ref(false);
const pending = ref(false);
// Simulated round trip: `loading` shows the spinner in place of the handle
// and `disabled` refuses further input until the server has answered.
// `loading` alone does not block clicks.
const onToggle = (event: CustomEvent<boolean>) => {
pending.value = true;
window.setTimeout(() => {
enabled.value = event.detail;
pending.value = false;
}, 1500);
};
</script>
API reference
<c-switch>
A toggle for a binary setting that takes effect immediately: a native switch control with a label.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | false | Whether the switch is on: the boolean view of `value`. Setting it sets `value` to `trueValue` or `falseValue`; reading it reports whether `value` equals `trueValue`. As an attribute it sets the initial state when no `value` is bound. |
disabled | disabled | boolean | false | If `true`, the switch is disabled and cannot be toggled |
falseValue | false-value | boolean | number | string | false | The value when the switch is off |
label | label | string | '' | Label of the switch, shown beside the toggle. Falls back to the default slot content when not set. |
loading | loading | boolean | false | Show a spinner in place of the handle, such as while the change is saved. The switch ignores toggles meanwhile and is announced as busy |
name | name | string | '' | The name the switch submits under in a native `<form>` while it is on: its `true-value`, or `on` when that is `true` |
required | required | boolean | false | Set as required — shows the required marker on the label |
trueValue | true-value | boolean | number | string | true | The value when the switch is on |
value | value | string | number | boolean | — | The switch's state: `trueValue` while it is on, `falseValue` while it is off. A bound value wins over a `checked` attribute; any other value, `''` included, reads as off. |
Events
| Event | Detail | Description |
|---|---|---|
change | boolean | number | string | Fired when the user toggles the switch, carrying the new value — `trueValue` when on, `falseValue` when off. |
input | void | Native bubbling input event fired on toggle so a plain Vue `v-model` stays in sync. No detail. |
update:value | boolean | number | string | Fired alongside `change` with the same detail — the `v-model` contract. |
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus its switch, as `focus()` does on a native control: the element renders no box of its own to take it. |
Slots
| Slot | Description |
|---|---|
default | The visible label of the switch (fallback when the `label` prop is not set) |
CSS parts
Style from outside with c-switch::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The `<label>` element wrapping the toggle and the label text |
slider | The toggle track (its `::before` pseudo-element is the handle) |
label | Wrapper around the label text or slotted label content |
Custom states
Select on the host's live state with c-switch:state(name) — combine with ::part() for per-state styling, e.g. c-switch:state(checked)::part(indicator) targets the indicator only while checked.
| State | Description |
|---|---|
checked | Present while the switch is on |