For regular selection take the ready-made controls — CdsCheckbox, CdsRadio, CdsToggle: they already have the icons, the sizes, the state colors and the block of messages. CdsSelectionControl is needed when the control you want is not in the library.

Anatomy

On the left is the control: the state icon from true-icon / false-icon and an invisible native input on top of it. On the right are the label (CdsLabel) and the description (CdsDescription); a click on the label toggles the control.

Storybook

The component has no sizes of its own: the area of the control is set by the --cds-selection-control-width and --cds-selection-control-height CSS variables, and the gap up to the label is the free space inside that area. In the examples below the distance is added with the gap-x-2 class.

Variations

Type and icons

The type prop sets the type of the native input — the behavior and the accessibility depend on it: a checkbox is turned on and off, a radio is only selected. The state icons come from true-icon and false-icon; without them the control has no visible part.

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 and description

The label prop names the option, description explains it. Name the option briefly in the label, and move the details — the price, the deadlines, the limitations — into the 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>

Values

By default the model holds true or false. The true-value and false-value props replace them with your own values — handy when what goes to the server is not a boolean.

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 selection

If the model is an array, the controls work in multiple mode: every control adds its value to it and removes it when unchecked. The mode is turned on automatically — the multiple prop is needed only to set it by hand. Comparing the values is the job of value-comparator, a deep comparison by default.

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>

States

disabled blocks the control and dims its color, readonly forbids changing the value while keeping the look. error puts the --error modifier on the root — the error color is drawn for it by the styles of the particular control, the base component has none.

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>

Colors

color sets the color of the selected control, base-color the color of an unselected one. The values are the colors of the design system palette.

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>

Layout

Inside a flex container the control stretches together with its neighbors. The inline prop leaves it the width of its content — that way the controls can stand in a row without extra gaps.

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>

Slots

Slots replace the content coming from the props and the markup of the control itself.

Slot	Description
default	Content inside the control area, before the input. Receives the classes and the background color styles
input	The whole markup of the control. Receives model, the ready inputNode and the current icon
label	Content of the label. Replaces label
description	Content of the description. Replaces 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>

Scenarios

A selection tile

The input slot replaces the icon with your own markup, and the native input from inputNode stays on top of it and catches the clicks and the focus. The size of the clickable area is set by the --cds-selection-control-width and --cds-selection-control-height variables, and the state arrives in the slot through 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>

Consent before submitting

The control does not show messages — that is the job of the CdsInput wrapper. Without it, render the error text next to the control and pass error to it: the modifier will come in handy for your styles.

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

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
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
falseIcon	IconValue | undefined	—	Icon of the unselected state
falseValue	any	—	Value for the false state.
id	string | undefined	—	Unique identifier of the component
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
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
readonly	boolean | null | undefined	null	Read-only state
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
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
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

Events

Name	Type	Description
update:modelValue	[value: any]	Fires when the model of the component changes.

Slots

Name	Type	Description
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
input	SelectionControlSlot	Slot for the default input element.
label	{ label: string | undefined; props: Record<string, any>; }	Default slot of the CdsLabel component

Exposed

Name	Type	Description
input	HTMLInputElement | undefined	Ref to the native input element — a checkbox or a radio button.
isFocused	boolean	Whether the control is focused.