If the buttons trigger actions instead of storing a choice, take CdsButtonGroup. To pick from a long list use CdsSelect, and inside forms — CdsRadioGroup.

Variations

Selection

By default a single button is selected, and clicking it again clears the choice. v-model receives the value of the button, or its index when no value is set.

Sandbox Storybook

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

const model = ref();
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral">
      <CdsButton text="Один" />
      <CdsButton text="Два" />
      <CdsButton text="Три" />
    </CdsButtonToggle>
    <span class="text-content-secondary">Выбрано: {{ model ?? '—' }}</span>
  </div>
</template>

Multiple selection

The multiple prop allows selecting several buttons — v-model becomes an array of values.

Sandbox Storybook

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

const model = ref([]);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" multiple>
      <CdsButton text="Жирный" />
      <CdsButton text="Курсив" />
      <CdsButton text="Подчёркнутый" />
    </CdsButtonToggle>
    <span class="text-content-secondary">Выбрано: {{ model.length ? model : '—' }}</span>
  </div>
</template>

The max prop limits the number of selected buttons: once the limit is reached, clicks on the remaining buttons add nothing to the selection.

Sandbox Storybook

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

const model = ref([]);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" multiple :max="2">
      <CdsButton text="Утро" />
      <CdsButton text="День" />
      <CdsButton text="Вечер" />
      <CdsButton text="Ночь" />
    </CdsButtonToggle>
    <span class="text-content-secondary">Выбрано: {{ model.length }} из 2</span>
  </div>
</template>

Mandatory selection

The mandatory prop keeps the last choice from being cleared — the group always stays in some state. With the 'force' value the first available button is selected automatically, even when v-model is empty.

Sandbox Storybook

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

const model = ref('left');
</script>

<template>
  <div class="flex justify-center">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" mandatory>
      <CdsButton text="Слева" value="left" />
      <CdsButton text="По центру" value="center" />
      <CdsButton text="Справа" value="right" />
    </CdsButtonToggle>
  </div>
</template>

Color of the active button

The active-color prop repaints the selected buttons — the choice stands out on panels crowded with controls.

Sandbox Storybook

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

const model = ref(0);
</script>

<template>
  <div class="flex justify-center">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" active-color="green">
      <CdsButton text="День" />
      <CdsButton text="Неделя" />
      <CdsButton text="Месяц" />
    </CdsButtonToggle>
  </div>
</template>

Group props

CdsButtonToggle is built on CdsButtonGroup and accepts all of its props: variant and size apply to every button at once, and the default variant is soft. active-color or color set the color of the selected button (brand by default), base-color the unselected ones (neutral by default); divided adds dividers, and direction="vertical" turns the group into a column.

Sandbox Storybook

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

const horizontal = ref();
const vertical = ref();
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsButtonToggle v-model="horizontal" variant="soft" color="neutral" divided>
      <CdsButton text="Один" />
      <CdsButton text="Два" />
      <CdsButton text="Три" />
    </CdsButtonToggle>

    <CdsButtonToggle v-model="vertical" variant="soft" color="neutral" direction="vertical" divided>
      <CdsButton text="Один" />
      <CdsButton text="Два" />
      <CdsButton text="Три" />
    </CdsButtonToggle>
  </div>
</template>

Guidelines

Storybook

Scenarios

View mode

The classic toggle group — switching between a list and a grid. Icon buttons with aria-label save space, mandatory guarantees that the list is always shown in one of the modes, and the neutral default look with size="sm" keeps the control from stealing attention from the content.

Sandbox Storybook

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

const view = ref('list');

const items = ['Ноутбук', 'Монитор', 'Клавиатура', 'Мышь'];
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col gap-2">
    <div class="flex items-center justify-between">
      <span class="text-content-primary">Товары</span>

      <CdsButtonToggle v-model="view" mandatory variant="soft" color="neutral" size="sm">
        <CdsButton icon="list-bullet" value="list" aria-label="Список" />
        <CdsButton icon="view-rows" value="cards" aria-label="Плитка" />
      </CdsButtonToggle>
    </div>

    <ul v-if="view === 'list'" class="flex flex-col gap-1">
      <li v-for="item in items" :key="item" class="rounded-200 bg-surface-secondary px-2 py-1">{{ item }}</li>
    </ul>

    <div v-else class="grid grid-cols-2 gap-1">
      <div v-for="item in items" :key="item" class="rounded-200 bg-surface-secondary p-4 text-center">
        {{ item }}
      </div>
    </div>
  </div>
</template>

Formatting toolbar

Text styles are independent of each other, so the group works with multiple: each button turns its own style on and off, and v-model collects the selected values into an array.

Sandbox Storybook

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

const format = ref<string[]>([]);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="format" variant="soft" color="neutral" multiple divided>
      <CdsButton icon="bold" value="bold" aria-label="Жирный" />
      <CdsButton icon="italic" value="italic" aria-label="Курсив" />
      <CdsButton icon="underline" value="underline" aria-label="Подчёркнутый" />
    </CdsButtonToggle>

    <p
      :class="{
        'font-bold': format.includes('bold'),
        italic: format.includes('italic'),
        underline: format.includes('underline')
      }"
    >
      Съешьте ещё этих мягких французских булок
    </p>
  </div>
</template>

Period filter

Give the buttons a value — and v-model returns a meaningful value to query the data with. mandatory keeps the user from ending up without a period: the numbers always belong to the selected range.

Sandbox Storybook

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

const period = ref<'day' | 'week' | 'month'>('week');

const stats = {
  day: { orders: 12, sum: '48 000 ₽' },
  week: { orders: 84, sum: '316 000 ₽' },
  month: { orders: 367, sum: '1,4 млн ₽' }
};
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="period" variant="soft" color="neutral" mandatory>
      <CdsButton text="День" value="day" />
      <CdsButton text="Неделя" value="week" />
      <CdsButton text="Месяц" value="month" />
    </CdsButtonToggle>

    <div class="flex w-[240px] flex-col items-center rounded-200 bg-surface-secondary p-4">
      <span class="text-900">{{ stats[period].orders }}</span>
      <span class="text-content-secondary">заказов на {{ stats[period].sum }}</span>
    </div>
  </div>
</template>

API

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
appearancedeprecated	"inverse" | "primary" | "secondary" | "tertiary" | "transparent" | undefined	—	Visual appearance of the component. Deprecated: use variant and color
baseColor	string | undefined	—	Color of the component in its inactive state
color	(string & {}) | "neutral" | "brand" | "accent" | "danger" | "inverse" | undefined	'brand'	Component color: a role, a palette alias, a theme token or a CSS color
direction	"horizontal" | "vertical" | undefined	'horizontal'	Switches the component between horizontal and vertical layout.
disabled	boolean | null | undefined	null	Disabled state
divided	boolean | undefined	—	Adds dividers between the buttons of the group.
mandatory	boolean | "force" | undefined	—	Requires at least one item to stay selected
max	number | undefined	—	Maximum number of items that can be selected
modelValue	any	—	Value of the selected items of the group
multiple	boolean | undefined	—	Allows selecting several items at once
required	boolean | "force" | undefined	—	Requires at least one item to stay selected
selectedClass	string | undefined	—	CSS class applied in the selected state
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
theme	string | undefined	—	Component theme
variant	"solid" | "soft" | "outline" | "surface" | "ghost" | undefined	'soft'	Buttons variant: solid, soft, outline, surface, ghost

Events

Name	Type	Description
update:modelValue	[value: unknown]	Fires when the selected value changes.

Slots

Name	Type	Description
default	CdsButtonToggleSlotProps	Buttons of the toggle group. The slot props expose the state of the group (selection, navigation).

Exposed

Name	Type	Description
isSelected	(id: string) => boolean	Checks whether the button with this id is selected
next	() => void	Selects the next button
prev	() => void	Selects the previous button
select	(id: string, value: boolean) => void	Selects a button by its id
selected	readonly string[]	Ids of the selected buttons