If the choice should look like buttons, take CdsButtonToggle. For a choice out of a long list use CdsSelect, and for separate independent tags without selection just use CdsTag.

Variations

Selection

Give every tag a value — exactly this value lands in v-model. Without value the index of the tag in the group becomes its value. A repeated click on the selected tag clears the selection.

Sandbox Storybook

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

const categories = ['Электроника', 'Одежда', 'Мебель', 'Спорт', 'Книги'];
const selected = ref('Электроника');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected">
      <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано: {{ selected ?? '—' }}</span>
  </div>
</template>

Multiple selection

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

Sandbox Storybook

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

const deliveries = ['Самовывоз', 'Курьер', 'Почта', 'Транспортная компания'];
const selected = ref(['Курьер', 'Почта']);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" multiple>
      <CdsTag v-for="delivery in deliveries" :key="delivery" :value="delivery" :text="delivery" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано: {{ selected.join(', ') || '—' }}</span>
  </div>
</template>

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

Sandbox Storybook

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

const deliveries = ['Самовывоз', 'Курьер', 'Почта', 'Транспортная компания'];
const selected = ref(['Курьер']);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" multiple :max="2">
      <CdsTag v-for="delivery in deliveries" :key="delivery" :value="delivery" :text="delivery" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано {{ selected.length }} из 2</span>
  </div>
</template>

Mandatory selection

The mandatory prop does not let you clear the last selection: a tag can only be switched. With the 'force' value the first available tag is selected automatically, even when v-model is empty.

Sandbox Storybook

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

const periods = ['Неделя', 'Месяц', 'Квартал', 'Год'];
const selected = ref('Месяц');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" mandatory>
      <CdsTag v-for="period in periods" :key="period" :value="period" :text="period" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">
      Период: {{ selected }} — снять выбор нельзя, можно только переключить
    </span>
  </div>
</template>

Selection indicator

The filter prop adds a check icon to the selected tags — the selection reads not only from the fill. The filter-icon prop of the tag changes the icon, and the filter slot replaces it with your own markup.

Sandbox Storybook

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

const statuses = ['Черновики', 'На проверке', 'Опубликованные', 'В архиве'];
const selected = ref(['На проверке']);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" multiple filter>
      <CdsTag v-for="status in statuses" :key="status" :value="status" :text="status" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано: {{ selected.join(', ') || '—' }}</span>
  </div>
</template>

Color and disabling

The group passes the color, active-color, disabled and filter props to its tags as defaults — there is no need to repeat them on every tag. color paints the unselected tags, active-color paints the selected one; without it the selected tag stays in the brand color so that the selection reads with any palette. disabled blocks the whole group: the selection is visible but cannot be switched. A prop set directly on a tag wins over the value of the group.

Sandbox Storybook

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

const formats = ['Отчёт', 'Презентация', 'Таблица'];
const colored = ref('Отчёт');
const active = ref('Отчёт');
const locked = ref('Презентация');
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">color — цвет невыбранных тегов</span>

      <CdsTagGroup v-model="colored" color="red">
        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
      </CdsTagGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">active-color — цвет выбранного тега</span>

      <CdsTagGroup v-model="active" color="green" active-color="red">
        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
      </CdsTagGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">disabled — выбор сохраняется, но недоступен</span>

      <CdsTagGroup v-model="locked" disabled>
        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
      </CdsTagGroup>
    </div>
  </div>
</template>

Layout

By default the tags stand in a single row, and the extra ones move into a horizontal scroll with arrows: the group is built on CdsSlideGroup and accepts its props — show-arrows, direction, center-active. The column prop wraps the tags into rows instead of scrolling — that way all the options are visible at once.

Sandbox Storybook

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

const categories = ['Электроника', 'Бытовая техника', 'Одежда', 'Обувь', 'Мебель', 'Спорт', 'Книги', 'Игрушки'];

const scrolled = ref('Электроника');
const wrapped = ref('Электроника');
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-1 text-content-secondary">По умолчанию — горизонтальная прокрутка со стрелками</span>

      <CdsTagGroup v-model="scrolled">
        <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
      </CdsTagGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-1 text-content-secondary">column — перенос по строкам</span>

      <CdsTagGroup v-model="wrapped" column>
        <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
      </CdsTagGroup>
    </div>
  </div>
</template>

Guidelines

Storybook

Scenarios

Catalog filter

A row of categories above the results is the most common job for a tag group. column shows all the categories at once, mandatory prevents ending up without a filter, and v-model gives you a ready key for the product request.

Sandbox Storybook

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

const products = [
  { name: 'Ноутбук Alfa 14', category: 'Ноутбуки', price: '68 900 ₽' },
  { name: 'Ноутбук Beta Pro', category: 'Ноутбуки', price: '94 500 ₽' },
  { name: 'Смартфон Gamma 5', category: 'Смартфоны', price: '32 400 ₽' },
  { name: 'Смартфон Delta Mini', category: 'Смартфоны', price: '21 900 ₽' },
  { name: 'Монитор Epsilon 27"', category: 'Мониторы', price: '27 300 ₽' }
];

const categories = ['Все', 'Ноутбуки', 'Смартфоны', 'Мониторы'];
const category = ref('Все');

const filtered = computed(() =>
  category.value === 'Все' ? products : products.filter((product) => product.category === category.value)
);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <CdsTagGroup v-model="category" column mandatory>
      <CdsTag v-for="item in categories" :key="item" :value="item" :text="item" />
    </CdsTagGroup>

    <div class="flex flex-col gap-1">
      <div
        v-for="product in filtered"
        :key="product.name"
        class="flex items-center justify-between rounded-200 bg-surface-secondary p-2"
      >
        <span>{{ product.name }}</span>
        <span class="text-100 text-content-secondary">{{ product.price }}</span>
      </div>
    </div>

    <span class="text-100 text-content-secondary">Найдено товаров: {{ filtered.length }}</span>
  </div>
</template>

Picking several topics

When the values do not exclude each other, turn on multiple. max keeps the selection within reasonable bounds, filter marks the selected topics with a check, and the hint under the group explains the limit.

Sandbox Storybook

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

const topics = ['Аналитика', 'Дизайн', 'Разработка', 'Маркетинг', 'Продажи', 'Логистика', 'Поддержка'];
const selected = ref(['Дизайн']);

const isFull = computed(() => selected.value.length >= 3);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <span>Выберите до трёх тем — по ним будем присылать дайджест</span>

    <CdsTagGroup v-model="selected" column multiple filter :max="3">
      <CdsTag v-for="topic in topics" :key="topic" :value="topic" :text="topic" />
    </CdsTagGroup>

    <span class="text-100" :class="isFull ? 'text-content-secondary' : 'text-content-tertiary'">
      {{ isFull ? 'Лимит достигнут — снимите тему, чтобы выбрать другую' : `Выбрано ${selected.length} из 3` }}
    </span>
  </div>
</template>

Switching the period

The group exposes the next, prev and select methods and the selected list — get them through a ref on the component. This is how tags get the back / forward arrows that walk through the periods in order.

Sandbox Storybook

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

const revenue: Record<string, string> = {
  'I квартал': '1,2 млн ₽',
  'II квартал': '1,8 млн ₽',
  'III квартал': '2,4 млн ₽',
  'IV квартал': '3,1 млн ₽'
};

const quarters = Object.keys(revenue);
const quarter = ref('II квартал');
const group = ref<InstanceType<typeof CdsTagGroup> | null>(null);
</script>

<template>
  <div class="m-auto flex w-[420px] flex-col items-center gap-2">
    <div class="flex items-center gap-1">
      <CdsFunctionalButton icon="chevron-left" aria-label="Предыдущий квартал" @click="group?.prev()" />

      <CdsTagGroup ref="group" v-model="quarter" mandatory>
        <CdsTag v-for="item in quarters" :key="item" :value="item" :text="item" />
      </CdsTagGroup>

      <CdsFunctionalButton icon="chevron-right" aria-label="Следующий квартал" @click="group?.next()" />
    </div>

    <div class="flex w-full flex-col items-center rounded-200 bg-surface-secondary p-4">
      <span class="text-900">{{ revenue[quarter] }}</span>
      <span class="text-content-secondary">выручка за {{ quarter.toLowerCase() }}</span>
    </div>
  </div>
</template>

API

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
centerActive	boolean | undefined	—	Forces the active component to be aligned to the center.
color	string | undefined	—	Component color
column	boolean | undefined	—	Lays the tags out in several rows with wrapping instead of a horizontal scroll.
contentClass	any	—	Adds classes to the slide group container
contentStyle	any	—	Adds inline styles to the slide group container
direction	"horizontal" | "vertical" | undefined	'horizontal'	Switches the component between horizontal and vertical layout.
disabled	boolean | null | undefined	null	Disabled state
filter	boolean | undefined	—	Shows a check icon on the selected tags (passed down to CdsTag).
mandatory	boolean | "force" | undefined	—	Requires at least one item to stay selected
max	number | undefined	—	Maximum number of items that can be selected
mobile	boolean | null | undefined	null	Determines the display mode of the component: true renders it in mobile mode, false in desktop mode, null makes the mode depend on the current breakpoint.
mobileBreakpoint	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	—	Sets the breakpoint at which the component switches to mobile mode. Accepts a number (for example, 600) or the name of a predefined breakpoint (xs, sm, md, lg, xl).
modelValue	any	—	Value of the selected items of the group
multiple	boolean | undefined	—	Allows selecting several items at once
nextIcon	IconValue | undefined	'chevron-right'	Icon for the “next” button.
prevIcon	IconValue | undefined	'chevron-left'	Icon for the “previous” button.
required	boolean | "force" | undefined	—	Requires at least one item to stay selected
scrollToActive	boolean | undefined	false	When true, the container scrolls the active component into view whenever it changes.
selectedClass	string | undefined	'cds-tag--selected'	CSS class applied in the selected state
showArrows	string | boolean | undefined	—	Changes how the arrows are shown. By default the arrows appear on desktop devices when the container overflows and stay hidden on mobile devices. true also shows them on mobile on overflow, desktop always shows them on desktop, mobile always on mobile, always on both, and never disables the arrows.
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
theme	string | undefined	—	Component theme

Events

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

Slots

Name	Type	Description
default	CdsTagGroupSlotProps	Tags of the group. The slot props expose the group state (selection, navigation).

Exposed

Name	Type	Description
isSelected	(id: string) => boolean	Check whether a tag with the given id is selected
next	() => void	Select the next tag
prev	() => void	Select the previous tag
select	(id: string, value: boolean) => void	Select a tag by id
selected	readonly string[]	Ids of the selected tags