To pick one option out of several use CdsRadio, for settings that apply immediately — CdsToggle. If you need the control alone, without a label and messages — in a table cell, for example — take CdsCheckboxButton.

Anatomy

A checkbox is made of the control with the state icon, the label with its description and the messages block under them. A click on the label toggles the checkbox exactly like a click on the control.

Storybook

Variations

Label and description

The label prop names the option, description adds an explanation under the label. The slots of the same name accept arbitrary markup — a link to the terms, for example (see the "Consent in a form" scenario).

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>

States

disabled blocks the checkbox and lowers the contrast, readonly forbids changes but does not change the appearance.

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 state

The indeterminate prop shows an intermediate state — usually on a parent checkbox when only some of the nested entries are selected. This is a visual flag: it does not change the model value, and the icon is set by indeterminate-icon. A live example is in the "Select all" scenario.

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>

Sizes

The size prop accepts values from xs to xl, md by default. The label and the description scale together with the control.

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>

Colors

The color prop sets the color of a selected checkbox, base-color — the color of an unselected one.

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

messages shows a supporting text under the checkbox, error-messages — a ready error message (the one coming from the server, for example) together with the error state. Validation rules through rules are in the "Consent in a form" scenario.

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>

Your own values

By default the model keeps true or false. The true-value and false-value props replace them with your own values — handy when the API expects strings or codes.

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>

A group of checkboxes

To build a group, pass the same array in v-model to all the checkboxes and give them unique values — the selected values are collected into the array. hide-details removes the bottom block and the rows sit right next to each other; the common heading and description of the group are set by CdsLabel and 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>

Guidelines

Storybook

Scenarios

Select all

The parent checkbox controls the group: a computed model checks and unchecks all the entries at once, and indeterminate turns on while only some of them are selected.

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>

Consent in a form

A required consent is a rule in rules that returns the error text while the checkbox is unchecked. The label slot adds a link to the terms into the label, and the button starts the check through the validate() of the 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>

Filtering a list

A group of checkboxes with an array in v-model filters the list on the fly: a computed keeps the documents of the selected types, and an empty selection means "show everything".

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

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
appendIcon	IconValue | undefined	—	Icon in the append slot, after the content
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
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	'checkbox-off'	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 checkbox.
indeterminateIcon	IconValue | undefined	'checkbox-indeterminate-fill'	Icon shown in the indeterminate state.
label	string | undefined	—	Label text of the component
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
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
trueIcon	IconValue | undefined	'checkbox-on-fill'	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: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
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

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