The built-in badge shows a status or a counter right on the avatar; for a marker on arbitrary content take CdsBadge, and for a text label inside a line — CdsTag.

Anatomy

An avatar is a container with one of three kinds of content and an optional badge in the top corner.

Storybook

Variations

Content

The content comes from one of three props: image — a photo, icon — an icon, text — initials. If you pass several of them, image wins, then icon.

Sandbox Storybook

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

<template>
  <div class="flex justify-center gap-3">
    <CdsAvatar image="https://i.pravatar.cc/120?img=12" />
    <CdsAvatar icon="user" color="brand-secondary" />
    <CdsAvatar text="ВМ" color="brand-primary" />
  </div>
</template>

Sizes

The size prop takes a token from xs to xl or a number of pixels. The default size is md.

Sandbox Storybook

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

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

<template>
  <div class="flex flex-col items-center gap-3">
    <div class="flex items-center justify-center gap-2">
      <CdsAvatar v-for="size in sizes" :key="size" :size="size" text="ВМ" color="brand-primary" />
      <CdsAvatar :size="72" text="ВМ" color="brand-primary" />
    </div>

    <div class="flex items-center justify-center gap-2">
      <CdsAvatar v-for="size in sizes" :key="size" :size="size" image="https://i.pravatar.cc/120?img=12" />
      <CdsAvatar :size="72" image="https://i.pravatar.cc/120?img=12" />
    </div>

    <div class="flex items-center justify-center gap-2">
      <CdsAvatar v-for="size in sizes" :key="size" :size="size" icon="user" color="brand-secondary" />
      <CdsAvatar :size="72" icon="user" color="brand-secondary" />
    </div>
  </div>
</template>

Colors

The color prop paints the background of an avatar with initials or an icon: a theme token or any CSS color will do.

Sandbox Storybook

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

const items = [
  { color: 'brand-primary', text: 'BP' },
  { color: 'brand-secondary', text: 'BS' },
  { color: '#0f9d58', text: 'GR' },
  { color: '#db4437', text: 'RD' },
  { color: '#673ab7', text: 'PR' }
];
</script>

<template>
  <div class="flex justify-center gap-2">
    <CdsAvatar v-for="item in items" :key="item.text" size="md" :color="item.color" :text="item.text" />
  </div>
</template>

Badge

The badge prop set to true shows a dot in the corner of the avatar. An object is passed through as props of CdsBadge: this is how you change the color of the dot, show a counter (dot: false plus content) or move the badge away from the edge (floating). The badge slot replaces the content of the badge with anything you like — an icon, for example.

Sandbox Storybook

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

<template>
  <div class="flex justify-center gap-3">
    <CdsAvatar size="lg" badge image="https://i.pravatar.cc/120?img=12" />
    <CdsAvatar size="lg" text="АД" color="brand-primary" :badge="{ color: 'status-success-surface' }" />
    <CdsAvatar size="lg" icon="user-group" color="brand-secondary" :badge="{ dot: false, content: 3 }" />
    <CdsAvatar size="lg" text="ОК" color="brand-secondary" :badge="{ dot: false, content: 12, floating: true }" />
    <CdsAvatar size="lg" image="https://i.pravatar.cc/120?img=32" :badge="{ color: 'status-success-surface' }">
      <template #badge>
        <CdsIcon icon="check" />
      </template>
    </CdsAvatar>
  </div>
</template>

Spacing

The start and end props add a margin on the side of the neighboring content: start — for an avatar at the beginning of a line, end — at the end. This way the avatar fits into text without wrappers that carry outer margins.

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-2">
    <div class="flex items-center justify-center">
      <CdsAvatar start size="sm" text="АД" color="brand-primary" />
      <span>Анна Дмитриева оставила комментарий</span>
    </div>

    <div class="flex items-center justify-center">
      <span>Задачу проверяет</span>
      <CdsAvatar end size="sm" image="https://i.pravatar.cc/80?img=32" />
    </div>
  </div>
</template>

Slots

Slot	Description
default	Avatar content. Replaces image, icon and text
badge	Badge content. Shown instead of the dot when badge is on

Guidelines

Storybook

Scenarios

Member list

In a list of people the avatar is a fast visual anchor. The start prop gives the margin before the text, photos and initials alternate depending on what the user has, and the badge dot shows who is online right now.

Sandbox Storybook

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

const members = [
  { name: 'Анна Дмитриева', role: 'Менеджер проекта', image: 'https://i.pravatar.cc/80?img=47', online: true },
  { name: 'Павел Соколов', role: 'Аналитик', text: 'ПС', color: 'brand-primary', online: false },
  { name: 'Мария Ильина', role: 'Дизайнер', image: 'https://i.pravatar.cc/80?img=32', online: true },
  { name: 'Служба поддержки', role: 'Общий канал', icon: 'user-group', color: 'brand-secondary', online: false }
];
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-3">
    <div v-for="member in members" :key="member.name" class="flex items-center">
      <CdsAvatar
        start
        :image="member.image"
        :icon="member.icon"
        :text="member.text"
        :color="member.color"
        :badge="member.online && { color: 'status-success-surface' }"
      />

      <div class="flex flex-col">
        <span>{{ member.name }}</span>
        <span class="text-200 text-content-secondary">{{ member.role }}</span>
      </div>
    </div>
  </div>
</template>

Group of members

When there are many members and little space, avatars are stacked with a slight overlap — a border in the background color separates the neighbors from each other. The last avatar with text="+3" tells how many people did not fit.

Sandbox Storybook

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

const images = [
  'https://i.pravatar.cc/80?img=12',
  'https://i.pravatar.cc/80?img=47',
  'https://i.pravatar.cc/80?img=32',
  'https://i.pravatar.cc/80?img=56'
];
</script>

<template>
  <div class="flex items-center justify-center gap-3">
    <div class="avatar-stack flex items-center">
      <CdsAvatar v-for="image in images" :key="image" :image="image" />
      <CdsAvatar text="+3" color="brand-secondary" />
    </div>

    <span class="text-content-secondary">7 участников</span>
  </div>
</template>

<style scoped>
.avatar-stack .cds-avatar {
  border: 2px solid var(--cds-color-surface-primary);
}

.avatar-stack .cds-avatar:not(:first-child) {
  margin-inline-start: -8px;
}
</style>

Uploading a profile photo

While there is no photo yet, the avatar shows the initials from text — the page is not left with an empty circle. As soon as image gets a link, the photo replaces the initials; after the photo is removed, the initials come back on their own.

Sandbox Storybook

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

const image = ref('');
const loading = ref(false);

const upload = async () => {
  loading.value = true;

  await new Promise((resolve) => setTimeout(resolve, 1200));

  image.value = 'https://i.pravatar.cc/160?img=47';
  loading.value = false;
};

const remove = () => {
  image.value = '';
};
</script>

<template>
  <div class="flex items-center justify-center gap-3">
    <CdsAvatar size="xl" :image="image" text="АД" color="brand-primary" />

    <CdsButton v-if="!image" prepend-icon="upload" text="Загрузить фото" :loading="loading" @click="upload" />
    <CdsButton v-else variant="soft" color="neutral" text="Удалить фото" @click="remove" />
  </div>
</template>

API

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
badge	boolean | CdsBadgeProps | undefined	false	Avatar badge. true shows a dot, an object is passed through as CdsBadge props.
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
color	string | undefined	—	Component color
content	string | number | undefined	—	Content displayed in the component.
end	boolean | undefined	—	Adds a margin on the left — for an avatar at the end of a line of content.
icon	IconValue | undefined	—	Icon shown in the avatar when no image is set.
image	string | undefined	—	Source of the avatar image. Takes priority over icon and text.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
start	boolean | undefined	—	Adds a margin on the right — for an avatar at the beginning of a line of content.
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

Slots

Name	Type	Description
badge	any	Content of the avatar badge.
default	any	Avatar content. Overrides image, icon and text.