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

Анатомия

Слева — контрол: иконка состояния из true-icon / false-icon и невидимый нативный input поверх неё. Справа — метка (CdsLabel) и описание (CdsDescription); клик по метке переключает контрол.

Storybook

Своих размеров у компонента нет: зону контрола задают CSS-переменные --cds-selection-control-width и --cds-selection-control-height, а отступ до метки — свободное место внутри этой зоны. В примерах ниже расстояние добавлено классом gap-x-2.

Вариации

Тип и иконки

Свойство type задаёт тип нативного input — от него зависят поведение и доступность: checkbox включается и выключается, radio только выбирается. Иконки состояний приходят из true-icon и false-icon; без них у контрола не будет видимой части.

Sandbox Storybook

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

const checkbox = ref(true);
const radio = ref(true);
const star = ref(true);
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsSelectionControl
      v-model="checkbox"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Чекбокс"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="radio"
      type="radio"
      true-icon="radio-on"
      false-icon="radio-off"
      label="Радиокнопка"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="star"
      type="checkbox"
      true-icon="star-fill"
      false-icon="star"
      label="Своя пара иконок"
      class="gap-x-2"
    />
  </div>
</template>

Метка и описание

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

Sandbox Storybook

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

const digest = ref(true);
const report = ref(false);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-3">
    <CdsSelectionControl
      v-model="digest"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Еженедельный дайджест"
      description="Письмо с новыми закупками по понедельникам"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="report"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Отчёт по заявкам"
      class="gap-x-2"
    />
  </div>
</template>

Значения

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

Sandbox Storybook

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

const delivery = ref('pickup');
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="delivery"
      type="checkbox"
      true-value="courier"
      false-value="pickup"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Доставка курьером"
      class="gap-x-2"
    />

    <span class="text-content-secondary">Значение модели: {{ delivery }}</span>
  </div>
</template>

Множественный выбор

Если в модели массив, контролы работают в режиме multiple: каждый добавляет в неё своё value и убирает при снятии. Режим включается автоматически — свойство multiple нужно, только чтобы задать его вручную. За сравнение значений отвечает value-comparator, по умолчанию — глубокое сравнение.

Sandbox Storybook

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

const channels = [
  { value: 'email', label: 'Почта' },
  { value: 'sms', label: 'SMS' },
  { value: 'push', label: 'Push-уведомления' }
];

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

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-for="channel of channels"
      :key="channel.value"
      v-model="selected"
      type="checkbox"
      :value="channel.value"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      :label="channel.label"
      class="gap-x-2"
    />

    <span class="text-content-secondary">Значение модели: {{ selected }}</span>
  </div>
</template>

Состояния

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

Sandbox Storybook

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

const readonly = ref(true);
const error = ref(true);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      :model-value="true"
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Обычное состояние"
      class="gap-x-2"
    />

    <CdsSelectionControl
      :model-value="true"
      disabled
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Заблокирован (disabled)"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="readonly"
      readonly
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Только для чтения (readonly)"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="error"
      error
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Ошибка (error)"
      class="gap-x-2"
    />
  </div>
</template>

Цвета

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

Sandbox Storybook

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

const selected = ref(true);
const unselected = ref(false);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="selected"
      color="green"
      base-color="purple"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Выбран: цвет из color"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="unselected"
      color="green"
      base-color="purple"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Не выбран: цвет из base-color"
      class="gap-x-2"
    />
  </div>
</template>

Компоновка

Внутри флекс-контейнера контрол растягивается наравне с соседями. Свойство inline оставляет ему ширину содержимого — так контролы можно поставить в ряд без лишних пустот.

Sandbox Storybook

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

const stretched = ref(['first']);
const inline = ref(['first']);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">По умолчанию контролы делят ширину поровну</span>

      <div class="flex">
        <CdsSelectionControl
          v-model="stretched"
          value="first"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Да"
          class="gap-x-2"
        />

        <CdsSelectionControl
          v-model="stretched"
          value="second"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Нет"
          class="gap-x-2"
        />
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">С inline контрол занимает ширину своего содержимого</span>

      <div class="flex gap-3">
        <CdsSelectionControl
          v-model="inline"
          inline
          value="first"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Да"
          class="gap-x-2"
        />

        <CdsSelectionControl
          v-model="inline"
          inline
          value="second"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Нет"
          class="gap-x-2"
        />
      </div>
    </div>
  </div>
</template>

Слоты

Слоты заменяют контент из пропсов и саму разметку контрола.

Слот	Описание
default	Контент внутри зоны контрола, перед input. Получает классы и стили цвета фона
input	Разметка контрола целиком. Получает model, готовый inputNode и текущую icon
label	Содержимое метки. Замещает label
description	Содержимое описания. Замещает description

Sandbox Storybook

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

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

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="beta"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      class="gap-x-2"
    >
      <template #label>
        <span class="flex items-center gap-1">
          Ранний доступ
          <CdsTag text="beta" size="sm" />
        </span>
      </template>

      <template #description> Новые возможности до общего релиза — <CdsLink href="#" text="что входит" /> </template>
    </CdsSelectionControl>
  </div>
</template>

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

Плитка выбора

Слот input заменяет иконку своей разметкой, а нативный input из inputNode остаётся поверх неё и ловит клики и фокус. Размер кликабельной зоны задают переменные --cds-selection-control-width и --cds-selection-control-height, состояние приходит в слот через model.

Sandbox Storybook

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

const plans = [
  { value: 'base', title: 'Базовый', price: '0 ₽ в месяц' },
  { value: 'pro', title: 'Профи', price: '2 900 ₽ в месяц' }
];

const plan = ref('base');
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsSelectionControl
      v-for="item of plans"
      :key="item.value"
      v-model="plan"
      inline
      type="radio"
      :value="item.value"
      :aria-label="item.title"
      :style="{ '--cds-selection-control-width': '170px', '--cds-selection-control-height': '72px' }"
    >
      <template #input="{ inputNode, model }">
        <component :is="inputNode" />

        <div
          class="flex h-full w-full flex-col justify-center rounded-200 border px-3"
          :class="model.value ? 'border-line-selected ring-1 ring-line-selected' : 'border-line-primary'"
        >
          <span>{{ item.title }}</span>
          <span class="text-content-secondary">{{ item.price }}</span>
        </div>
      </template>
    </CdsSelectionControl>
  </div>
</template>

Согласие перед отправкой

Сообщения контрол не показывает — за них отвечает обвязка CdsInput. Без неё выводите текст ошибки рядом, а error передайте контролу: модификатор пригодится вашим стилям.

Sandbox Storybook

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

const agreed = ref(false);
const touched = ref(false);
const sent = ref(false);

function submit() {
  touched.value = true;
  sent.value = agreed.value;
}
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="agreed"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      :error="touched && !agreed"
      class="gap-x-2"
    >
      <template #label> Согласен с <CdsLink href="#" text="условиями обработки данных" /> </template>
    </CdsSelectionControl>

    <span v-if="touched && !agreed" class="text-status-danger-content">Без согласия заявку не отправить</span>
    <span v-else-if="sent" class="text-status-success-content">Заявка отправлена</span>

    <CdsButton text="Отправить заявку" class="self-start" @click="submit" />
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
baseColor	string | undefined	—	Цвет неактивного компонента
bgColor	string | undefined	—	Цвет фона компонента
color	string | undefined	—	Цвет компонента
defaultsTarget	string | undefined	—	Имя дочернего компонента, которому пробрасываются значения пропсов группы по умолчанию
description	string | undefined	—	Описание компонента, отображаемое под меткой
direction	"horizontal" | "vertical" | undefined	'horizontal'	Переключение между горизонтальным или вертикальным отображением.
disabled	boolean | null | undefined	null	Заблокированное состояние
error	boolean | undefined	—	Переводит компонент в визуальное состояние ошибки
falseIcon	IconValue | undefined	—	Иконка невыбранного состояния
falseValue	any	—	Значение для false состояния.
id	string | undefined	—	Уникальный идентификатор компонента
inline	boolean | undefined	—	Отображает контрол как inline-элемент — контейнер не растягивается на всю ширину
label	string | undefined	—	Текст метки (label) компонента
modelValue	any	—	Значение компонента (v-model). В группе — значение выбранного контрола, при multiple — массив выбранных значений
multiple	boolean | null | undefined	null	Разрешает выбор нескольких значений — модель становится массивом. Включается автоматически, если в modelValue передан массив
name	string | undefined	—	Атрибут name нативного элемента input. В группе одно имя объединяет все вложенные контролы
readonly	boolean | null | undefined	null	Только для чтения
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента
trueIcon	IconValue | undefined	—	Иконка выбранного состояния
trueValue	any	—	Значение для true состояния.
type	string | undefined	—	Тип нативного элемента input — например, radio или checkbox
value	any	—	Значение, используемое при выборе компонента в группе. Если оно не указано, будет использоваться уникальный идентификатор.
valueComparator	ValueComparator | undefined	true	Функция сравнения значения модели со значением value контрола. По умолчанию — глубокое сравнение

События

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

Слоты

Имя	Тип	Описание
default	{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }	Слот по-умолчанию
description	{ description: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsDescription
input	SelectionControlSlot	Слот для элемента ввода по умолчанию.
label	{ label: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsLabel

Exposed

Имя	Тип	Описание
input	HTMLInputElement | undefined	Ссылка на нативный элемент input — чекбокс или радиокнопку.
isFocused	boolean	Находится ли элемент управления в фокусе.