Для выбора одного варианта из нескольких используйте CdsRadio, для настроек, которые применяются сразу, — CdsToggle. Если нужен только контрол без лейбла и сообщений — например, в ячейке таблицы — возьмите CdsCheckboxButton.

Анатомия

Чекбокс собран из контрола с иконкой состояния, лейбла с описанием и блока сообщений под ними. Клик по лейблу переключает чекбокс так же, как клик по контролу.

Storybook

Вариации

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

Свойство label называет опцию, description добавляет пояснение под лейблом. Одноимённые слоты принимают произвольную разметку — например, ссылку на условия (см. сценарий «Согласие в форме»).

Sandbox Storybook

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

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox v-model="completed" label="Показывать завершённые задачи" hide-details />
    <CdsCheckbox
      v-model="autoRenew"
      label="Автоматическое продление"
      description="Подписка продлится в день окончания текущего периода"
      hide-details
    />
  </div>
</template>

Состояния

disabled блокирует чекбокс и снижает контрастность, readonly запрещает изменение, но не меняет внешний вид.

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox label="Disabled" disabled hide-details />
    <CdsCheckbox :model-value="true" label="Disabled, выбран" disabled hide-details />
    <CdsCheckbox :model-value="true" label="Readonly" readonly hide-details />
  </div>
</template>

Неопределённое состояние

Свойство indeterminate показывает промежуточное состояние — обычно у родительского чекбокса, когда выбрана только часть вложенных пунктов. Это визуальный флаг: значение модели он не меняет, иконку задаёт indeterminate-icon. Живой пример — в сценарии «Выбрать всё».

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox indeterminate label="Выбрана часть вложенных пунктов" hide-details />
    <CdsCheckbox :model-value="true" label="Выбран" hide-details />
    <CdsCheckbox label="Не выбран" hide-details />
  </div>
</template>

Размеры

Свойство size принимает значения от xs до xl, по умолчанию — md. Вместе с контролом масштабируются лейбл и описание.

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox :model-value="true" size="xs" label="Размер xs" hide-details />
    <CdsCheckbox :model-value="true" size="sm" label="Размер sm" hide-details />
    <CdsCheckbox :model-value="true" size="md" label="Размер md" hide-details />
    <CdsCheckbox :model-value="true" size="lg" label="Размер lg" hide-details />
    <CdsCheckbox :model-value="true" size="xl" label="Размер xl" hide-details />
  </div>
</template>

Цвета

Свойство color задаёт цвет выбранного чекбокса, base-color — цвет невыбранного.

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox :model-value="true" color="green" label="Зелёный при выборе (color)" hide-details />
    <CdsCheckbox :model-value="true" color="purple" label="Фиолетовый при выборе (color)" hide-details />
    <CdsCheckbox base-color="purple" label="Фиолетовый до выбора (base-color)" hide-details />
  </div>
</template>

Сообщения и ошибки

messages показывает вспомогательный текст под чекбоксом, error-messages — готовое сообщение об ошибке (например, пришедшее с сервера) вместе с состоянием ошибки. Правила валидации через rules — в сценарии «Согласие в форме».

Sandbox Storybook

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

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox v-model="notifications" label="Уведомления о торгах" messages="Можно отключить в любой момент" />
    <CdsCheckbox label="Передача данных партнёрам" error-messages="Для участия в торгах разрешите передачу данных" />
  </div>
</template>

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

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

Sandbox Storybook

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

const subscription = ref('subscribed');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCheckbox
      v-model="subscription"
      true-value="subscribed"
      false-value="unsubscribed"
      label="Получать рассылку"
      hide-details
    />

    <p>Значение модели: {{ subscription }}</p>
  </div>
</template>

Группа чекбоксов

Чтобы собрать группу, передайте всем чекбоксам один массив в v-model и уникальные value — выбранные значения складываются в массив. hide-details убирает нижний блок, и строки встают вплотную; общий заголовок и описание группы задают CdsLabel и CdsDescription.

Sandbox Storybook

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

const selected = ref(['email']);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsLabel class="text-sm mb-1">Способы связи</CdsLabel>
    <CdsDescription class="text-xs mb-2">Как связаться с вами по заявке</CdsDescription>
    <div class="flex flex-col gap-2">
      <CdsCheckbox v-model="selected" label="Электронная почта" hide-details value="email" />
      <CdsCheckbox v-model="selected" label="Телефон" hide-details value="phone" />
      <CdsCheckbox v-model="selected" label="Telegram" hide-details value="telegram" />
    </div>

    <p>Выбрано: {{ selected }}</p>
  </div>
</template>

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

Storybook

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

Выбрать всё

Родительский чекбокс управляет группой: вычисляемая модель отмечает и снимает все пункты сразу, а indeterminate включается, пока выбрана только часть.

Sandbox Storybook

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

const options = ['Договоры', 'Счета', 'Акты сверки'];
const selected = ref(['Договоры']);

const allSelected = computed({
  get: () => selected.value.length === options.length,
  set: (value) => {
    selected.value = value ? [...options] : [];
  }
});

const partiallySelected = computed(() => selected.value.length > 0 && selected.value.length < options.length);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsCheckbox v-model="allSelected" :indeterminate="partiallySelected" label="Выбрать всё" hide-details />
    <div class="flex flex-col gap-1 mt-1 pl-4">
      <CdsCheckbox
        v-for="option in options"
        :key="option"
        v-model="selected"
        :value="option"
        :label="option"
        hide-details
      />
    </div>
  </div>
</template>

Согласие в форме

Обязательное согласие — правило в rules, которое возвращает текст ошибки, пока чекбокс снят. Слот label добавляет в лейбл ссылку на условия, кнопка запускает проверку через validate() формы CdsForm.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsCheckbox, CdsForm, CdsLink } from '@central-design-system/components';
import { ref, unref } from 'vue';

const consent = ref(false);
const sending = ref(false);
const formRef = ref<InstanceType<typeof CdsForm>>();

const rules = [(value: boolean) => !!value || 'Для регистрации примите условия сервиса'];

async function submit() {
  const form = unref(formRef);
  if (!form) return;

  const { valid } = await form.validate();
  if (!valid) return;

  sending.value = true;
  setTimeout(() => {
    sending.value = false;
  }, 1500);
}
</script>

<template>
  <CdsForm ref="formRef" class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox v-model="consent" :rules="rules">
      <template #label> Принимаю <CdsLink href="#">условия сервиса</CdsLink> </template>
    </CdsCheckbox>

    <CdsButton text="Зарегистрироваться" :loading="sending" @click="submit" />
  </CdsForm>
</template>

Фильтр по списку

Группа чекбоксов с массивом в v-model фильтрует список на лету: computed оставляет документы выбранных типов, а пустой выбор означает «показать всё».

Sandbox Storybook

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

const documents = [
  { name: 'Договор поставки № 14', type: 'Договор' },
  { name: 'Счёт № 209', type: 'Счёт' },
  { name: 'Акт сверки за июнь', type: 'Акт' },
  { name: 'Договор аренды № 7', type: 'Договор' },
  { name: 'Счёт № 218', type: 'Счёт' }
];

const types = ['Договор', 'Счёт', 'Акт'];
const selectedTypes = ref<string[]>([]);

const filtered = computed(() =>
  selectedTypes.value.length ? documents.filter((document) => selectedTypes.value.includes(document.type)) : documents
);
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <div class="flex flex-wrap gap-3">
      <CdsCheckbox v-for="type in types" :key="type" v-model="selectedTypes" :value="type" :label="type" hide-details />
    </div>

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="document in filtered" :key="document.name">{{ document.name }}</li>
    </ul>
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
appendIcon	IconValue | undefined	—	Иконка в слоте append после контента
baseColor	string | undefined	—	Цвет неактивного компонента
bgColor	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	'checkbox-off'	Иконка невыбранного состояния
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	—	Неопределенное состояние чекбокса.
indeterminateIcon	IconValue | undefined	'checkbox-indeterminate-fill'	Иконка для отображения в неопределенном состоянии.
label	string | undefined	—	Текст метки (label) компонента
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'	Размер компонента
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента
trueIcon	IconValue | undefined	'checkbox-on-fill'	Иконка выбранного состояния
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: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
message	CdsMessageSlot	Слот для настройки содержания сообщения
messages	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
prepend	CdsInputSlot	Добавляет элемент до поля ввода

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[]>	Функция валидации поля ввода