`<c-switch>`

A toggle for a binary setting that takes effect immediately: a native switch control with a label, an optional hint, and validation messaging.

Usage

Bind the state with a plain v-model (or the checked prop); true-value / false-value map the on/off state onto custom values.

<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.

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

Basic

Vue

React

Angular

TypeScript

<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>

Label

Vue

React

Angular

TypeScript

<template>
  <c-switch label="Email notifications" required />
</template>

API reference

`<c-switch>`

A toggle for a binary setting that takes effect immediately: a native switch control with a label, an optional hint, and validation messaging.

Properties

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	If `true`, the checkbox is selected.
`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 checkbox is unchecked
`hostId`	`host-id`	`string`	`''`	Id for the element
`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`	Loading state
`required`	`required`	`boolean`	`false`	Set as required
`trueValue`	`true-value`	`boolean \| number \| string`	`true`	The value when the checkbox is checked
`value`	`value`	`boolean \| number \| string`	`false`	The input value - Only used when the checkbox participates in a native `<form>`

Events

Event	Detail	Description
`change`	`void`	Standard bubbling DOM change event, re-dispatched from the host when the switch is toggled (the inner input's change does not cross the shadow boundary). No detail; read the new value from the host's `value` property.
`changeValue`	`boolean \| number \| string`	Fired when the switch is toggled, carrying the new value — `trueValue` when on, `falseValue` when off. Also dispatched as `change-value` — bind that name in Vue templates.
`input`	`void`	Native bubbling input event fired on toggle so a plain Vue `v-model` works without the `v-control` directive. No detail.
`update:value`	`boolean \| number \| string`	v-model contract event fired on toggle, carrying the new value — `trueValue` when on, `falseValue` when off.

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).

State	Description
`checked`	Present while the switch is on