Avatar
Компонент для отображения аватара: изображение по URL с fallback на инициалы из имени, несколько размеров и форм (круг / квадрат), палитра фонов.
Демо
appearancebadgechildrendata-test-idnameshapeshowTwoSymbolssizesrcstatus<Avatar appearance="neutral" shape="rounded" showTwoSymbols={false} size="s" name="Jane Doe" />Когда использовать
- Идентификатор пользователя в хедере, меню, списке участников.
- Автор комментария, сообщения, коммита.
- Плейсхолдер для отсутствующего фото — инициалы из имени.
Когда не нужен Avatar: если требуется декоративная иконка или логотип бренда — используйте обычный <img> или иконку.
Анатомия
Size
Размерный ряд аватара: xs/s — для плотных списков и тулбаров, m — дефолт в рядах, l — карточки пользователей, 3xl/6xl/9xl — крупные профили и пустые состояния.
Shape
Форма контейнера: rounded — круглый (по умолчанию для людей), squared — со скруглёнными углами (команды, организации, боты).
Appearance
Цвет фона под инициалами. Помимо нейтрального neutral есть декоративные red, orange, yellow, green, blue, violet, pink — используются для стабильной окраски по id пользователя, не несут семантики.
Badge
Слот для микро-индикатора в правом-нижнем углу аватара. Принимает любой ReactNode:
StatusIndicator— задаётся коротким пропомstatus(компонент сам подбирает размер).Counter— счётчик уведомлений.- Иконка-«verified» / собственный микро-компонент — через
badge={<...>}.
Для визуальной парности с дефолтным StatusIndicator бери размер из публичной карты AVATAR_TO_STATUS_INDICATOR_SIZE[size].
Установка
pnpm add @cloud-ru/ds-avatarimport { Avatar, APPEARANCE, SHAPE, SIZE } from '@cloud-ru/ds-avatar'Примеры использования
Инициалы из имени
import { Avatar } from '@cloud-ru/ds-avatar';
export function Initials() {
return <Avatar name='Иван Петров' />;
}С изображением
import { Avatar } from '@cloud-ru/ds-avatar';
export function WithImage() {
return <Avatar src='https://i.pravatar.cc/80?img=12' name='Анна Смирнова' />;
}Разные размеры
import { Avatar } from '@cloud-ru/ds-avatar';
export function Sizes() {
return (
<div style={{ display: 'flex', gap: 12, flexWrap: 'wrap', alignItems: 'center' }}>
<Avatar size='s' name='АС' />
<Avatar size='m' name='АС' />
<Avatar size='l' name='АС' />
</div>
);
}Кастомный badge-слот
import { Avatar, AVATAR_TO_STATUS_INDICATOR_SIZE, SIZE } from '@cloud-ru/ds-avatar';
import { Counter, SIZE as COUNTER_SIZE } from '@cloud-ru/ds-counter';
import { CheckSVG } from '@cloud-ru/ds-icons/interface/system';
import { APPEARANCE as STATUS_APPEARANCE, StatusIndicator } from '@cloud-ru/ds-status';
import styles from './CustomBadge.module.scss';
export function CustomBadge() {
return (
<div style={{ display: 'flex', gap: 16, flexWrap: 'wrap', alignItems: 'center' }}>
<Avatar
name='John Doe'
size={SIZE['6Xl']}
src='https://i.pravatar.cc/120?img=12'
badge={<Counter value={5} size={COUNTER_SIZE.S} />}
/>
<Avatar
name='Jane Roe'
size={SIZE['6Xl']}
src='https://i.pravatar.cc/120?img=47'
badge={
<span className={styles.verified}>
<CheckSVG size={16} />
</span>
}
/>
<Avatar
name='Alex Roe'
size={SIZE['6Xl']}
src='https://i.pravatar.cc/120?img=8'
status={STATUS_APPEARANCE.Green}
/>
<Avatar
name='Mia Roe'
size={SIZE['6Xl']}
src='https://i.pravatar.cc/120?img=20'
badge={
<StatusIndicator size={AVATAR_TO_STATUS_INDICATOR_SIZE[SIZE['6Xl']]} appearance={STATUS_APPEARANCE.Red} />
}
/>
</div>
);
}Props
Types
AvatarProps| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
appearance | "blue" | "green" | "neutral" | "orange" | "pink" | "red" | "violet" | "yellow" | neutral | no | Внешний вид (цвет) |
badge | ReactNode | — | no | Произвольный нод в слот значка (правый-нижний угол). Перекрывает `status`. |
children | string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | null | undefined | — | no | |
className | string | — | no | CSS-класс |
data-test-id | string | — | no | |
innerRef | Ref<HTMLDivElement> | — | no | Ref на корневой DOM-элемент. Используем явный проп, чтобы не зависеть от `forwardRef` и не тащить type-assertions на экспорт. |
name | string | — | yes | Имя пользователя для генерации аббревиатуры |
shape | "rounded" | "squared" | rounded | no | Форма: круглая или квадратная |
showTwoSymbols | boolean | false | no | Отображение двух заглавных символов имени вместо одного |
size | "3xl" | "6xl" | "9xl" | "l" | "m" | "s" | "xs" | m | no | Размер |
src | string | — | no | URL изображения аватара |
status | "blue" | "green" | "neutral" | "orange" | "pink" | "red" | "violet" | "yellow" | — | no | Appearance дефолтного `StatusIndicator` в правом-нижнем углу. Размер индикатора подбирается из `size` аватара автоматически. Полностью настроить значок можно через слот `badge`, который перекрывает `status`. |
Unions
Types
AvatarProps
Unions
Appearance
Shape
Size
Related props
StatusAppearance
Принимает вспомогательные атрибуты data-test-id и ARIA через тип WithSupportProps из @cloud-ru/ds-utils, а также стандартные атрибуты контейнера HTMLDivElement.