To build a toggle or a filter with selection out of tags, take CdsTagGroup. For a counter or a dot indicator on top of another element use CdsBadge, and trigger actions with CdsButton — a tag only labels.

Anatomy

A tag consists of a container and content areas: prepend and append carry an icon or an avatar, the text lives in the center, and the close button appears with closable.

Storybook

Variations

Colors

The color prop paints the tag in one of the 11 palette aliases; without it the tag stays neutral gray. The text color can be overridden with text-color when needed. The disabled prop swaps the tag colors for the service colors of the disabled state and removes the reaction to clicks.

Sandbox Storybook

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

const colors = CdsTag.constants.colors;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsTag v-for="color in colors" :key="color" :text="color" :color="color" />
  </div>
</template>

Sizes

The size prop offers five sizes from xs to xl. The default size is md.

Sandbox Storybook

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

const sizes = CdsTag.constants.sizes;
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTag v-for="size in sizes" :key="size" :text="size" :size="size" />
  </div>
</template>

Shape

The pill prop rounds the corners completely — this shape emphasizes that the label stands on its own and looks good in a tag cloud.

Sandbox Storybook

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

<template>
  <div class="flex justify-center gap-2">
    <CdsTag text="Обычный тег" />
    <CdsTag pill text="Тег pill" />
  </div>
</template>

Icons and avatars

The prepend-icon and append-icon props add an icon before and after the text, prepend-avatar and append-avatar add a round avatar. The size of the icon and the avatar follows the size of the tag.

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTag prepend-icon="star" text="Избранное" />
    <CdsTag append-icon="external-link" text="b2b-center.ru" />
    <CdsTag prepend-avatar="https://i.pravatar.cc/80?img=12" text="Анна Ветрова" pill />
  </div>
</template>

Slots

Slots replace the content coming from props when you need full control over the markup.

Slot	Description
default	Content of the tag. Replaces the text from text
prepend	Content before the text. Replaces prepend-icon / prepend-avatar
append	Content after the text. Replaces append-icon / append-avatar
close	Content of the close button. Replaces the icon from close-icon
filter	Content of the selection indicator in a group. Replaces the icon from filter-icon

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsTag color="green">Скидка <b>−20%</b></CdsTag>
    <CdsTag text="Избранное">
      <template #prepend>
        <CdsIcon icon="star-fill" start />
      </template>
    </CdsTag>
    <CdsTag text="Черновик" closable>
      <template #close>
        <CdsIcon icon="delete" />
      </template>
    </CdsTag>
  </div>
</template>

Link tag

Pass href (or to with a RouteLocationRaw object from vue-router) and the tag renders as an a tag: it gets a cursor, keyboard focus and navigation on Enter, keeping the look of a tag.

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsTag href="https://www.b2b-center.ru" target="_blank" append-icon="external-link" text="b2b-center.ru" />
    <CdsTag href="#" pill text="vue" />
    <CdsTag href="#" pill text="design-system" />
  </div>
</template>

Closing

The closable prop (or its alias removable) adds a close button. A click on it hides the tag and emits the click:close event, and the visibility can be controlled from the outside through v-model. The close-icon prop changes the icon of the button, close-label changes the accessible label.

Sandbox Storybook

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

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

<template>
  <div class="flex items-center justify-center gap-4">
    <CdsTag v-model="visible" closable text="Закрываемый тег" />
    <CdsButton v-if="!visible" variant="soft" color="brand" size="sm" text="Вернуть тег" @click="visible = true" />
  </div>
</template>

Selection in a group

Inside CdsTagGroup a tag becomes a toggle: value sets its value in the group, the selected state is marked with the cds-tag--selected class, and the group:selected event reports the change of selection. With filter the selected tag gets an indicator — filter-icon changes the icon, the filter slot changes the whole markup. The default slot exposes isSelected, toggle and select — a handy base for your own tag markup.

The color of the selected tag comes from active-color: without it the group itself paints the selection with the brand color, and color stays the color of the unselected tag.

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" filter>
      <CdsTag v-for="status in statuses" :key="status" :value="status" :text="status" />
    </CdsTagGroup>

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

Guidelines

Storybook

Scenarios

Selected filters

Applied search filters read well as a row of closable tags: each tag removes its own filter on click:close, and the neighboring tertiary button resets everything at once.

Sandbox Storybook

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

const initial = ['Электроника', 'До 10 000 ₽', 'В наличии', 'Доставка завтра', 'Рейтинг 4+'];
const filters = ref([...initial]);

const remove = (filter: string) => {
  filters.value = filters.value.filter((item) => item !== filter);
};
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTag v-for="filter in filters" :key="filter" :text="filter" closable @click:close="remove(filter)" />
    <CdsButton
      v-if="filters.length"
      variant="soft"
      color="neutral"
      size="sm"
      text="Сбросить всё"
      @click="filters = []"
    />
    <CdsButton v-else variant="soft" color="brand" size="sm" text="Вернуть фильтры" @click="filters = [...initial]" />
  </div>
</template>

Record statuses

In lists and tables a colored tag shows the state of a record instantly. Assign colors to statuses once: green — success, lemon — pending, red — rejection, neutral — draft. The compact size="sm" does not compete with the text of the row.

Sandbox Storybook

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

const requests = [
  { id: 4821, title: 'Закупка ноутбуков', status: 'Согласована', color: 'green' },
  { id: 4820, title: 'Ремонт офиса', status: 'На рассмотрении', color: 'lemon' },
  { id: 4819, title: 'Аренда склада', status: 'Отклонена', color: 'red' },
  { id: 4818, title: 'Поставка канцелярии', status: 'Черновик', color: 'neutral' }
];
</script>

<template>
  <div class="flex flex-col gap-2 w-[360px] m-auto">
    <div v-for="request in requests" :key="request.id" class="flex items-center justify-between gap-4">
      <span>{{ request.title }}</span>
      <CdsTag :text="request.status" :color="request.color" size="sm" />
    </div>
  </div>
</template>

Adding labels

An input field together with tags makes a label editor: Enter adds a new label, the cross (closable + click:close) removes an extra one. Duplicates are cut off before they get into the list.

Sandbox Storybook

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

const input = ref('');
const tags = ref(['vue', 'design-system']);

const add = () => {
  const value = input.value.trim();

  if (value && !tags.value.includes(value)) {
    tags.value.push(value);
  }

  input.value = '';
};

const remove = (tag: string) => {
  tags.value = tags.value.filter((item) => item !== tag);
};
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsTextInput v-model="input" label="Метки" placeholder="Введите метку и нажмите Enter" @keydown.enter="add" />
    <div class="flex flex-wrap gap-2">
      <CdsTag v-for="tag in tags" :key="tag" :text="tag" closable @click:close="remove(tag)" />
    </div>
  </div>
</template>

API

Props

Name	Type	Default	Description
activeClass	string | undefined	—	CSS class applied to the active (selected) link tag.
activeColor	string | undefined	—	Color of the component in its active state
appendAvatar	string | undefined	—	Avatar displayed after (to the right of) the tag content.
appendIcon	IconValue | undefined	—	Icon displayed after (to the right of) the tag content.
closable	boolean | undefined	—	Adds a close button that hides the tag.
closeIcon	IconValue | undefined	'remove'	Icon of the close button.
closeLabel	string | undefined	'$cds.close'	Accessible label (aria-label) for the close button.
color	string | undefined	—	Component color
content	string | number | undefined	—	Content displayed in the component.
disabled	boolean | null | undefined	null	Disabled state
draggable	boolean | undefined	—	Makes the tag draggable (native drag-and-drop).
exact	boolean | undefined	—	If true, the active state applies only on an exact route match
filter	boolean | undefined	—	Shows the selection indicator icon when the tag is used inside a group (CdsTagGroup).
filterIcon	IconValue | undefined	'check'	Icon of the selection indicator (relevant together with filter).
href	string | undefined	—	The href attribute of the link. When set, the component behaves as a regular link
label	boolean | undefined	—	Applies the “label” style with a smaller corner radius.
link	boolean | undefined	—	Gives the tag the styles and the behavior of a link.
modelValue	boolean | undefined	true	Visibility of the tag (v-model). When false the tag is not rendered.
pill	boolean | undefined	—	Makes the corners of the tag fully rounded.
prependAvatar	string | undefined	—	Avatar displayed before (to the left of) the tag content.
prependIcon	IconValue | undefined	—	Icon displayed before (to the left of) the tag content.
removable	boolean | undefined	—	Adds a remove button (alias for closable).
replace	boolean | undefined	—	If true, navigation replaces the current history entry instead of pushing a new one
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	'span'	Custom HTML tag or component to render
text	string | number | undefined	—	Text displayed in the component.
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
to	LinkTo | undefined	—	Target route or route location object for RouterLink. When set, the component behaves as a RouterLink
value	any	—	Value of the component within the group

Events

Name	Type	Description
click	[e: MouseEvent | KeyboardEvent]	Click on the tag (with a mouse or from the keyboard).
click:close	[e: MouseEvent]	Click on the close button of the tag.
group:selected	[value: { value: boolean; }]	Change of the tag selection state inside a group.
update:modelValue	[value: boolean]	Change of the tag visibility (v-model).

Slots

Name	Type	Description
append	any	Content after the main content (in place of the append icon/avatar).
close	any	Custom content of the close button.
default	{ isSelected: boolean | undefined; selectedClass: boolean | (string | undefined)[] | undefined; select: ((value: boolean) => void) | undefined; toggle: (() => void) | undefined; value: unknown; disabled: boolean; }	Default content of the tag. The slot props expose the group state (selection, toggling).
filter	any	Custom content of the selection indicator (relevant together with filter).
label	any	Content of the tag label.
prepend	any	Content before the main content (in place of the prepend icon/avatar).