A toggle changes the setting instantly. If the choice is applied together with the rest of the form by a button, take CdsCheckbox, and to pick one option out of a set — CdsRadioGroup.

Anatomy

On the left is the track with the thumb: their position and color show the state. On the right are the label and the description of the setting, at the bottom is the messages block. A click on the label toggles the switch exactly like a click on the track.

Storybook

Variations

Label and description

label names the setting, description explains what turning it on leads to. Phrase the label so that it is clear what happens in the on position.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const notifications = ref(true);
const autoRenew = ref(false);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="notifications" label="Уведомления о новых закупках" hide-details />
    <CdsToggle
      v-model="autoRenew"
      label="Автопродление подписки"
      description="Спишем оплату за день до окончания периода"
      hide-details
    />
  </div>
</template>

Sizes

Five sizes on the size scale — from xs to xl, md by default.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const sizes = CdsToggle.constants.sizes;
const enabled = ref(true);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-for="size in sizes" :key="size" v-model="enabled" :size="size" :label="size" hide-details />
  </div>
</template>

States

disabled blocks the toggle and lowers the contrast, readonly forbids changing the value, error paints the track with the error color. indeterminate is the undefined state: the thumb stops in the middle while the value is unknown — when only some of the nested options are on, for example. The first toggle removes it.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

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

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="off" label="Выключен" hide-details />
    <CdsToggle v-model="on" label="Включён" hide-details />
    <CdsToggle v-model="off" label="Disabled (выключен)" disabled hide-details />
    <CdsToggle v-model="on" label="Disabled (включён)" disabled hide-details />
    <CdsToggle v-model="on" label="Readonly" readonly hide-details />
    <CdsToggle v-model="off" label="Ошибка" error hide-details />
    <CdsToggle v-model="mixed" :indeterminate="true" label="Неопределённое состояние" hide-details />
  </div>
</template>

Loading and icons

loading shows an indicator inside the thumb — handy while the setting is being saved on the server; a string value sets the color of the loader. true-icon and false-icon add an icon to the thumb for each position.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const loading = ref(true);
const icon = ref(true);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="loading" loading label="Загрузка" hide-details />
    <CdsToggle v-model="icon" true-icon="success-fill" false-icon="error-fill" label="Иконки в бегунке" hide-details />
  </div>
</template>

Colors

color paints the track of a switched-on toggle, base-color — of a switched-off one, thumb-color — the thumb. The values are the names of the palette colors.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

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

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle
      v-model="on"
      color="brand-primary"
      label="Основной цвет дорожки во включённом положении (color)"
      hide-details
    />
    <CdsToggle v-model="off" base-color="purple" label="Фиолетовая дорожка в выключенном (base-color)" hide-details />
    <CdsToggle v-model="thumb" thumb-color="red" label="Красный бегунок (thumb-color)" hide-details />
  </div>
</template>

Your own values

By default the model is true/false. true-value and false-value bind the toggle to your own values — to an API field with a string status, for example.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const status = ref('public');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsToggle v-model="status" true-value="public" false-value="private" label="Открытый профиль" hide-details />
    <span>Значение модели: «{{ status }}»</span>
  </div>
</template>

Messages

messages shows a hint under the toggle, error-messages — a ready error message together with the error state. hide-details removes the bottom block entirely.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const backup = ref(true);
const newsletter = ref(false);
</script>

<template>
  <div class="flex flex-col gap-3 w-[350px] m-auto">
    <CdsToggle v-model="backup" label="Резервное копирование" messages="Копия создаётся каждую ночь в 03:00" />
    <CdsToggle
      v-model="newsletter"
      label="Рассылка по подписчикам"
      :error-messages="['Подтвердите домен, чтобы включить рассылку']"
    />
  </div>
</template>

Slots

When the text props are not enough, parts of the component are replaced by slots.

Slot name	Description
label	Label content (replaces label)
description	Description content (replaces description)
thumb	Thumb content; receives the current icon and the model
track-true / track-false	Track content in the on / off position
loader	Custom loading indicator
prepend / append	Elements before and after the control
messages / details	Content of the messages block / the whole bottom block

In the demo the thumb slot changes the icon of the thumb depending on the value, and track-true and track-false show icons on the track.

Sandbox Storybook

<script setup lang="ts">
import { CdsIcon, CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const visible = ref(true);
const annual = ref(true);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="visible" label="Профиль виден в поиске" hide-details>
      <template #thumb>
        <CdsIcon :icon="visible ? 'visibility' : 'visibility-off'" />
      </template>
    </CdsToggle>

    <CdsToggle v-model="annual" size="xl" label="Годовая оплата" hide-details>
      <template #track-true>
        <CdsIcon icon="success-fill" :size="16" />
      </template>
      <template #track-false>
        <CdsIcon icon="error-fill" :size="16" />
      </template>
    </CdsToggle>
  </div>
</template>

Guidelines

Storybook

Scenarios

Notification settings

The main toggle controls the whole group: while notifications are off, the channels are blocked through disabled. The choice of channels is kept though — after switching back on the group returns to its previous values.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const enabled = ref(true);
const channels = ref({ email: true, push: false, sms: false });
</script>

<template>
  <div class="flex flex-col gap-3 w-[320px] m-auto">
    <CdsToggle v-model="enabled" label="Уведомления" description="Сообщим о событиях в ваших закупках" hide-details />

    <div class="flex flex-col gap-3 pl-8">
      <CdsToggle v-model="channels.email" :disabled="!enabled" size="sm" label="Электронная почта" hide-details />
      <CdsToggle v-model="channels.push" :disabled="!enabled" size="sm" label="Push в браузере" hide-details />
      <CdsToggle v-model="channels.sms" :disabled="!enabled" size="sm" label="СМС" hide-details />
    </div>
  </div>
</template>

Saving on the server

The setting is saved right after the switch: while the request is in flight the toggle shows loading and does not accept clicks because of readonly. If the server rejected the change, the value comes back and the reason is shown in error-messages. Try switching the toggle off.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const enabled = ref(true);
const loading = ref(false);
const errors = ref<string[]>([]);

const save = async (value: unknown) => {
  loading.value = true;
  errors.value = [];

  // Имитация запроса к серверу
  await new Promise((resolve) => setTimeout(resolve, 1000));

  loading.value = false;

  if (!value) {
    enabled.value = true;
    errors.value = ['Отключить двухфакторную аутентификацию может только администратор'];
  }
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsToggle
      v-model="enabled"
      label="Двухфакторная аутентификация"
      description="Код из приложения при каждом входе"
      :loading="loading"
      :readonly="loading"
      :error-messages="errors"
      @update:model-value="save"
    />
  </div>
</template>

Paid options

Every toggle adds an option to the plan, and the total is recalculated at once — the user sees the consequences of the choice before paying.

Sandbox Storybook

<script setup lang="ts">
import { CdsToggle } from '@central-design-system/components';
import { computed, ref } from 'vue';

const options = [
  { key: 'analytics', label: 'Расширенная аналитика', description: 'Отчёты по закупкам и конкурентам', price: 900 },
  { key: 'support', label: 'Приоритетная поддержка', description: 'Ответ в течение часа', price: 500 },
  { key: 'api', label: 'Доступ к API', description: 'Интеграция с вашей ERP', price: 1500 }
] as const;

const selected = ref<Record<string, boolean>>({ analytics: true, support: false, api: false });

const total = computed(() => options.reduce((sum, option) => sum + (selected.value[option.key] ? option.price : 0), 0));
</script>

<template>
  <div class="flex flex-col gap-3 w-[350px] m-auto">
    <CdsToggle
      v-for="option in options"
      :key="option.key"
      v-model="selected[option.key]"
      :label="`${option.label} — ${option.price} ₽/мес`"
      :description="option.description"
      hide-details
    />

    <span class="font-semibold">Итого: {{ total }} ₽/мес</span>
  </div>
</template>

API

Props

Name	Type	Default	Description
appendIcon	IconValue | undefined	—	Icon in the append slot, after the content
baseColor	string | undefined	—	Color of the component in its inactive state
centerAffix	boolean | undefined	true	Vertically center the appendInner, prependInner, clearIcon and label elements.
color	string | undefined	—	Component color
defaultsTarget	string | undefined	—	Name of the child component the group prop values are passed to as defaults
description	string | undefined	—	Description of the component, shown under the label
direction	"horizontal" | "vertical" | undefined	'horizontal'	Switches the component between horizontal and vertical layout.
disabled	boolean | null | undefined	null	Disabled state
error	boolean | undefined	—	Puts the component into the visual error state
errorMessages	string | readonly string[] | null | undefined	[]	Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the rules prop. This field does not trigger validation.
falseIcon	IconValue | undefined	—	Icon of the unselected state
falseValue	any	—	Value for the false state.
focused	boolean | undefined	—	Controls the focus state of the component. When true, the component is considered focused and may apply the corresponding styles or behavior.
hideDetails	boolean | "auto" | undefined	—	Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages
hideMessages	boolean | undefined	—	Hide the messages under the input
hint	string | undefined	—	Hint text shown under the input
iconColor	string | boolean | undefined	—	Icon color. Accepts a boolean or a color string
id	string | undefined	—	Unique identifier of the component
indeterminate	boolean | undefined	—	Indeterminate state of the toggle.
inline	boolean | undefined	—	Renders the control as an inline element — the container does not stretch to the full width
label	string | undefined	—	Label text of the component
loading	string | boolean | undefined	false	Loading indicator. Accepts a boolean or a string with the color of the loader.
maxErrors	string | number | undefined	1	Maximum number of validation errors shown
maxWidth	string | number | undefined	—	Maximum component width
messages	string | readonly string[] | undefined	[]	Messages shown under the input
minWidth	string | number | undefined	—	Minimum component width
modelValue	any	—	Value of the component (v-model). In a group it is the value of the selected control, with multiple — an array of the selected values
multiple	boolean | null | undefined	null	Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to modelValue
name	string | undefined	—	The name attribute of the native input element. In a group one name joins all the nested controls
persistentHint	boolean | undefined	—	Always show the hint, not only on focus
prependIcon	IconValue | undefined	—	Icon in the prepend slot, before the content
readonly	boolean | null | undefined	null	Read-only state
rules	readonly ValidationRule[] | undefined	[]	Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
theme	string | undefined	—	Component theme
thumbColor	string | undefined	—	Color of the thumb.
trueIcon	IconValue | undefined	—	Icon of the selected state
trueValue	any	—	Value for the true state.
type	string | undefined	—	Type of the native input element — radio or checkbox, for example
validateOn	ValidateOn | undefined	—	Changes the type of the event that triggers validation
validationValue	any	—	Value used when applying the validation rules
value	any	—	Value used when the component is selected inside a group. When it is not set, a unique identifier is used.
valueComparator	ValueComparator | undefined	true	Function comparing the model value with the value of the control. Deep comparison by default
width	string | number | undefined	—	Component width

Events

Name	Type	Description
update:focused	[focused: boolean]	Fires when the focus state of the component changes.
update:indeterminate	[value: boolean]	Fires when the indeterminate state changes.
update:modelValue	[value: any]	Fires when the model of the component changes.

Slots

Name	Type	Description
append	CdsInputSlot	Adds an element after the input
default	{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }	Default slot
description	{ description: string | undefined; props: Record<string, any>; }	Default slot of the CdsDescription component
details	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
input	SelectionControlSlot	Slot for the default input element.
label	{ label: string | undefined; props: Record<string, any>; }	Default slot of the CdsLabel component
loader	LoaderSlotProps	Slot for a custom loading indicator.
message	CdsMessageSlot	Slot for customizing the content of a message
messages	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
prepend	CdsInputSlot	Adds an element before the input
thumb	{ icon: IconValue | undefined; } & CdsToggleSlot	Slot for the content of the thumb.
track-false	CdsToggleSlot	Slot for the content of the off part of the track.
track-true	CdsToggleSlot	Slot for the content of the on part of the track.

Exposed

Name	Type	Description
isDirty	boolean	Whether the input is dirty
isDisabled	boolean	Whether the input is disabled
isPure	boolean	Whether the input is pure
isReadonly	boolean	Whether the input is read-only
isValid	boolean | null	Whether the input is valid
isValidating	boolean	Whether the input is being validated
reset	() => Promise<void>	Resets the input to its initial state
resetValidation	() => Promise<void>	Resets the validation of the input
validate	(silent?: boolean) => Promise<string[]>	Validates the input