CSC Design System v4.0.0
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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

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>
Loading
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
checkedcheckedbooleanfalse 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.
disableddisabledbooleanfalse If `true`, the switch is disabled and cannot be toggled
falseValuefalse-valueboolean | number | stringfalse The value when the switch is off
labellabelstring'' Label of the switch, shown beside the toggle. Falls back to the default slot content when not set.
loadingloadingbooleanfalse 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
namenamestring'' The name the switch submits under in a native `<form>` while it is on: its `true-value`, or `on` when that is `true`
requiredrequiredbooleanfalse Set as required — shows the required marker on the label
trueValuetrue-valueboolean | number | stringtrue The value when the switch is on
valuevaluestring | 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

EventDetailDescription
changeboolean | number | stringFired when the user toggles the switch, carrying the new value — `trueValue` when on, `falseValue` when off.
inputvoidNative bubbling input event fired on toggle so a plain Vue `v-model` stays in sync. No detail.
update:valueboolean | number | stringFired alongside `change` with the same detail — the `v-model` contract.

Methods

MethodSignatureDescription
focus(options?: FocusOptions): voidFocus its switch, as `focus()` does on a native control: the element renders no box of its own to take it.

Slots

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

PartDescription
rootThe `<label>` element wrapping the toggle and the label text
sliderThe toggle track (its `::before` pseudo-element is the handle)
labelWrapper 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.

StateDescription
checkedPresent while the switch is on