Тумблер меняет настройку мгновенно. Если выбор применяется вместе с остальной формой по кнопке — возьмите CdsCheckbox, а для выбора одного варианта из набора — CdsRadioGroup.

Анатомия

Слева — дорожка с бегунком: положение и цвет показывают состояние. Справа — лейбл и описание настройки, внизу — блок сообщений. Клик по лейблу переключает тумблер так же, как клик по дорожке.

Storybook

Вариации

Лейбл и описание

label называет настройку, description поясняет последствия включения. Формулируйте лейбл так, чтобы было понятно, что произойдёт во включённом положении.

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>

Размеры

Пять размеров по шкале size — от xs до xl, по умолчанию md.

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>

Состояния

disabled блокирует тумблер и снижает контрастность, readonly запрещает менять значение, error красит дорожку цветом ошибки. indeterminate — неопределённое состояние: бегунок останавливается посередине, пока значение неизвестно — например, включена лишь часть вложенных опций. Первое переключение снимает его.

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 показывает индикатор в бегунке — удобно, пока настройка сохраняется на сервере; строковое значение задаёт цвет загрузчика. true-icon и false-icon добавляют в бегунок иконку для каждого положения.

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>

Цвета

color красит дорожку включённого тумблера, base-color — выключенного, thumb-color — бегунок. Значения — имена цветов палитры.

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>

Свои значения

По умолчанию модель — true/false. true-value и false-value привязывают тумблер к своим значениям — например, к полю API со строковым статусом.

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 выводит подсказку под тумблером, error-messages — готовое сообщение об ошибке вместе с состоянием ошибки. hide-details убирает нижний блок целиком.

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>

Слоты

Когда текстовых пропсов недостаточно, части компонента заменяются слотами.

Имя слота	Описание
label	Содержимое лейбла (замещает label)
description	Содержимое описания (замещает description)
thumb	Содержимое бегунка; получает текущую иконку и модель
track-true / track-false	Содержимое дорожки во включённом / выключенном положении
loader	Кастомный индикатор загрузки
prepend / append	Элементы до и после контрола
messages / details	Содержимое блока сообщений / нижний блок целиком

В демо слот thumb меняет иконку бегунка в зависимости от значения, а track-true и track-false показывают иконки на дорожке.

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>

Рекомендации

Storybook

Сценарии использования

Настройки уведомлений

Главный тумблер управляет всей группой: пока уведомления выключены, каналы заблокированы через disabled. Выбор каналов при этом сохраняется — после включения группа возвращается к прежним значениям.

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>

Сохранение на сервере

Настройка сохраняется сразу после переключения: пока идёт запрос, тумблер показывает loading и не принимает клики через readonly. Если сервер отклонил изменение, значение возвращается, а причина выводится в error-messages. Попробуйте выключить тумблер.

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>

Платные опции

Каждый тумблер добавляет опцию к тарифу, итоговая стоимость пересчитывается сразу — пользователь видит последствия выбора до оплаты.

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

Пропсы

Имя	Тип	По умолчанию	Описание
appendIcon	IconValue | undefined	—	Иконка в слоте append после контента
baseColor	string | undefined	—	Цвет неактивного компонента
centerAffix	boolean | undefined	true	Выровнять по вертикали элементы appendInner, prependInner, clearIcon и label по центру.
color	string | undefined	—	Цвет компонента
defaultsTarget	string | undefined	—	Имя дочернего компонента, которому пробрасываются значения пропсов группы по умолчанию
description	string | undefined	—	Описание компонента, отображаемое под меткой
direction	"horizontal" | "vertical" | undefined	'horizontal'	Переключение между горизонтальным или вертикальным отображением.
disabled	boolean | null | undefined	null	Заблокированное состояние
error	boolean | undefined	—	Переводит компонент в визуальное состояние ошибки
errorMessages	string | readonly string[] | null | undefined	[]	Отображает компонент в состояние ошибки и передает пользовательские сообщения об ошибках. Будет объединяться с любыми проверками, заданными в свойстве rules. Это поле не запускает валидацию.
falseIcon	IconValue | undefined	—	Иконка невыбранного состояния
falseValue	any	—	Значение для false состояния.
focused	boolean | undefined	—	Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение.
hideDetails	boolean | "auto" | undefined	—	Скрытие блока с деталями (сообщениями и подсказками). При значении 'auto' блок скрывается, если нет сообщений
hideMessages	boolean | undefined	—	Скрыть сообщения под полем ввода
hint	string | undefined	—	Текст подсказки, отображаемый под полем ввода
iconColor	string | boolean | undefined	—	Цвет иконки. Принимает булево значение или строку с цветом
id	string | undefined	—	Уникальный идентификатор компонента
indeterminate	boolean | undefined	—	Неопределённое состояние переключателя.
inline	boolean | undefined	—	Отображает контрол как inline-элемент — контейнер не растягивается на всю ширину
label	string | undefined	—	Текст метки (label) компонента
loading	string | boolean | undefined	false	Индикатор загрузки. Принимает булево значение или строку с цветом загрузчика.
maxErrors	string | number | undefined	1	Максимальное число отображаемых ошибок при валидации
maxWidth	string | number | undefined	—	Максимальная ширина компонента
messages	string | readonly string[] | undefined	[]	Сообщения для отображения под полем ввода
minWidth	string | number | undefined	—	Минимальная ширина компонента
modelValue	any	—	Значение компонента (v-model). В группе — значение выбранного контрола, при multiple — массив выбранных значений
multiple	boolean | null | undefined	null	Разрешает выбор нескольких значений — модель становится массивом. Включается автоматически, если в modelValue передан массив
name	string | undefined	—	Атрибут name нативного элемента input. В группе одно имя объединяет все вложенные контролы
persistentHint	boolean | undefined	—	Всегда отображать подсказку, а не только при фокусе
prependIcon	IconValue | undefined	—	Иконка в слоте prepend перед контентом
readonly	boolean | null | undefined	null	Только для чтения
rules	readonly ValidationRule[] | undefined	[]	Принимает массив, состоящий из элементов различных типов: функций, логических значений и строк. Функции принимают входное значение в качестве аргумента и должны возвращать либо true / false, либо строку, содержащую сообщение об ошибке. Поле ввода перейдет в состояние ошибки, если функция возвращает значение false (или любое значение в массиве содержит false) либо является строкой.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
theme	string | undefined	—	Тема компонента
thumbColor	string | undefined	—	Цвет бегунка.
trueIcon	IconValue | undefined	—	Иконка выбранного состояния
trueValue	any	—	Значение для true состояния.
type	string | undefined	—	Тип нативного элемента input — например, radio или checkbox
validateOn	ValidateOn | undefined	—	Изменяет тип события, при котором запускается валидация
validationValue	any	—	Значение, используемое при применении правил валидации
value	any	—	Значение, используемое при выборе компонента в группе. Если оно не указано, будет использоваться уникальный идентификатор.
valueComparator	ValueComparator | undefined	true	Функция сравнения значения модели со значением value контрола. По умолчанию — глубокое сравнение
width	string | number | undefined	—	Ширина компонента

События

Имя	Тип	Описание
update:focused	[focused: boolean]	Событие, которое срабатывает при изменении состояния фокуса компонента.
update:indeterminate	[value: boolean]	Событие, которое срабатывает при изменении неопределённого состояния.
update:modelValue	[value: any]	Событие, которое срабатывает при изменении модели компонента.

Слоты

Имя	Тип	Описание
append	CdsInputSlot	Добавляет элемент после поля ввода
default	{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }	Слот по-умолчанию
description	{ description: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsDescription
details	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
input	SelectionControlSlot	Слот для элемента ввода по умолчанию.
label	{ label: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsLabel
loader	LoaderSlotProps	Слот для кастомного индикатора загрузки.
message	CdsMessageSlot	Слот для настройки содержания сообщения
messages	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
prepend	CdsInputSlot	Добавляет элемент до поля ввода
thumb	{ icon: IconValue | undefined; } & CdsToggleSlot	Слот для содержимого «бегунка» (thumb).
track-false	CdsToggleSlot	Слот для содержимого выключенной части дорожки (track).
track-true	CdsToggleSlot	Слот для содержимого включённой части дорожки (track).

Exposed

Имя	Тип	Описание
isDirty	boolean	Является ли поле ввода "грязным"
isDisabled	boolean	Является ли поле ввода заблокированным
isPure	boolean	Является ли поле ввода "чистым"
isReadonly	boolean	Является ли поле ввода только для чтения
isValid	boolean | null	Является ли поле ввода валидным
isValidating	boolean	Является ли поле ввода в процессе валидации
reset	() => Promise<void>	Функция сброса поля ввода в исходное состояние
resetValidation	() => Promise<void>	Функция сброса валидации поля ввода
validate	(silent?: boolean) => Promise<string[]>	Функция валидации поля ввода