For a textual object status ("Done", "In progress") take CdsStatus, and CdsAvatar has a built-in badge prop for the common indicators on an avatar.

Anatomy

The badge attaches to the element from the default slot and is positioned relative to it. The content is a number or text from content, an icon from icon, or the markup from the badge slot.

Storybook

Variations

Content

The content prop sets what the badge shows — most often a counter of events. By default the badge sits in the top right corner of the element from the slot.

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsBadge content="10">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>

The max prop caps the counter: anything above it collapses into "99+". Without max the value is printed in full.

Sandbox Storybook

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

<template>
  <div class="flex justify-center gap-4">
    <CdsBadge content="150">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="150" :max="99">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>

Besides a number, content accepts a short text — a "new section" mark in a menu, for example. Here the badge is placed into the line by the inline prop — more on it in the positioning section.

Sandbox Storybook

<script setup lang="ts">
import { CdsBadge, CdsCard, CdsList, CdsListItem } from '@central-design-system/components';
</script>

<template>
  <CdsCard class="m-auto w-[200px]">
    <CdsList>
      <CdsListItem value="0">
        <template #title>Главная</template>
      </CdsListItem>
      <CdsListItem value="1">
        <template #title>Входящие</template>
        <template #append>
          <CdsBadge content="new" inline />
        </template>
      </CdsListItem>
      <CdsListItem value="2">
        <template #title>Исходящие</template>
      </CdsListItem>
    </CdsList>
  </CdsCard>
</template>

The icon prop shows an icon instead of text.

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsBadge icon="check" inline />
  </div>
</template>

Dot

The dot prop shrinks the badge to a dot and hides its content — only the "there is something new" signal is left. The diameter is changed via dot-size.

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsBadge dot>
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>

Colors

The color prop accepts any color alias of the design system, text-color changes the color of the content. By default the badge is red — the color of indication.

Sandbox Storybook

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

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

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

Positioning

By default the badge is positioned absolutely relative to the element from the slot. The location prop picks the corner.

Sandbox Storybook

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

<template>
  <div class="flex justify-center gap-4">
    <CdsBadge content="1" location="top end">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="2" location="bottom end">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="3" location="top start">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="4" location="bottom start">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>

The floating prop moves the badge 8 pixels away from the content, so it overlaps the element less. For fine-tuning there are offset-x and offset-y.

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsBadge content="3" floating>
      <CdsButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>

The inline prop puts the badge into the flow next to the content — as in the menu example above. location, floating and offset-* are ignored then.

Visibility

The model-value prop shows and hides the badge. The change of state is animated, and the animation is configured through transition.

Sandbox Storybook

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

const visible = ref(false);
const toggle = () => {
  visible.value = !visible.value;
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsBadge content="5" :model-value="visible" :inline="false">
      <CdsButton variant="soft" color="brand" @click="toggle"> {{ visible ? 'Скрыть' : 'Показать' }} бейдж </CdsButton>
    </CdsBadge>
  </div>
</template>

Slots

Slot	Description
default	The element the badge is attached to
badge	Badge content. Replaces content and icon

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsBadge>
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />

      <template #badge> Alert </template>
    </CdsBadge>
  </div>
</template>

Guidelines

Storybook

Scenarios

Notification center

A counter on the notifications icon: max keeps the badge compact for any number of events, and model-value hides it once nothing is unread — an empty "0" does not hang on the icon.

Sandbox Storybook

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

const unread = ref(3);
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsBadge :content="unread" :model-value="unread > 0" :max="99">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>

    <div class="flex flex-wrap justify-center gap-2">
      <CdsButton variant="soft" color="brand" text="Новое уведомление" @click="unread++" />
      <CdsButton variant="soft" color="brand" text="+100" @click="unread += 100" />
      <CdsButton variant="soft" color="neutral" text="Прочитать все" :disabled="unread === 0" @click="unread = 0" />
    </div>
  </div>
</template>

Menu with updates

Counters in menu items hint where to look. A badge with inline goes into the append slot of a list item, and once the section is opened model-value removes it. Open "Входящие" — the counter disappears.

Sandbox Storybook

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

const sections = ref([
  { title: 'Входящие', unread: 12 },
  { title: 'Задачи', unread: 3 },
  { title: 'Архив', unread: 0 }
]);
</script>

<template>
  <CdsCard class="m-auto w-[240px]">
    <CdsList>
      <CdsListItem v-for="section in sections" :key="section.title" :value="section.title" @click="section.unread = 0">
        <template #title>{{ section.title }}</template>
        <template #append>
          <CdsBadge :content="section.unread" :model-value="section.unread > 0" inline />
        </template>
      </CdsListItem>
    </CdsList>
  </CdsCard>
</template>

Contacts online

A dot indicator shows the state without words: color="green" — the contact is online, neutral — not. inline puts the dot into the list row, and the label prop announces the state to screen readers.

Sandbox Storybook

<script setup lang="ts">
import { CdsBadge, CdsCard, CdsList, CdsListItem } from '@central-design-system/components';

const contacts = [
  { name: 'Анна Савельева', online: true },
  { name: 'Пётр Максимов', online: true },
  { name: 'Мария Ким', online: false }
];
</script>

<template>
  <CdsCard class="m-auto w-[240px]">
    <CdsList>
      <CdsListItem v-for="contact in contacts" :key="contact.name" :value="contact.name">
        <template #prepend>
          <CdsBadge
            dot
            inline
            :color="contact.online ? 'green' : 'neutral'"
            :label="contact.online ? 'В сети' : 'Не в сети'"
          />
        </template>
        <template #title>{{ contact.name }}</template>
      </CdsListItem>
    </CdsList>
  </CdsCard>
</template>

API

Props

Name	Type	Default	Description
color	string | undefined	—	Component color
content	string | number | undefined	—	Content displayed in the component.
dot	boolean | undefined	—	Shrinks the component and hides its content, rendering it as a dot
dotSize	string | number | undefined	—	Dot size
floating	boolean | undefined	—	Moves the component further away from the content — an 8 pixel offset.
height	string | number | undefined	—	Component height
icon	IconValue | undefined	—	Icon shown inside the component. Ignored when the dot prop is set.
inline	boolean | undefined	—	Renders as an inline block instead of using absolute positioning. The location, floating and offset props are ignored.
label	string | undefined	'$cds.badge'	Aria-label for the component. Falls back to the default value when not set.
location	Anchor | null | undefined	'top end'	Position of the element relative to its container, for example "top left", "center", "bottom right".
max	string | number | undefined	—	Sets the maximum allowed value when content holds a number. If the number exceeds the maximum, a "+" suffix is added.
maxHeight	string | number | undefined	—	Maximum component height
maxWidth	string | number | undefined	—	Maximum component width
minHeight	string | number | undefined	—	Minimum component height
minWidth	string | number | undefined	—	Minimum component width
modelValue	boolean | undefined	true	Controls whether the component is shown or hidden.
offsetX	string | number | undefined	—	Offset along the X axis
offsetY	string | number | undefined	—	Offset along the Y axis
tag	string | JSXComponent<any> | undefined	'div'	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
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	'fade-transition'	Transition animation
width	string | number | undefined	—	Component width

Slots

Name	Type	Description
badge	any	Slot for the content placed inside the badge.
default	any	Default slot