﻿---
description: Компонент для отображения аватара пользователя — фотографии, инициалов или графики. Наследует все свойства HTML-элемента `<img>`.
tags: media
---

# Avatar \[tag:component]

Компонент для отображения аватара пользователя — фотографии, инициалов или графики. Наследует все свойства HTML-элемента `<img>`.

## Основные варианты

### Изображение

Основной вариант, использует стандартный `<img>` под капотом.

```jsx
<Avatar src="https://avatars.githubusercontent.com/u/61377022?s=50" alt="Фото пользователя" />
```

### Инициалы

Отображаются, если изображение не удалось загрузить или передано пустое свойство `src`.

```jsx
<Avatar initials="ВК" />
```

Рекомендации по использованию инициалов:

* рекомендуемая длина — не более 2 символов;
* размер шрифта автоматически адаптируется под размер аватара.

#### Градиентный фон

Помимо стандартного фона инициалы можно размещать на градиентном фоне.
Всего поддерживается 6 видов разных градиентов.

```jsx
<Avatar initials="ВК" gradientColor={6} />
```

При необходимости можно использовать кастомный градиент (с помощью `className`/`style`):

```jsx
<Avatar gradientColor="custom" style={{ backgroundImage: 'linear-gradient(...)' }} />
```

> Может быть полезна функция [`calcInitialsAvatarColor`](#calcinitialsavatarcolor).

## Размеры

```jsx
{return [16, 20, 24, 28, 32, 36, 40, 44, 48, 56, 64, 72, 80, 88, 96].map((size) => (
  <Avatar key={size} src="https://avatars.githubusercontent.com/u/32414396?s=100" size={size} />
))}
```

## Дополнительные элементы

### Бейдж

```jsx
<Avatar src="https://avatars.githubusercontent.com/u/26322098?s=56" size={56}>
  <Avatar.Badge background="stroke">
    <Icon20GiftCircleFillRed />
  </Avatar.Badge>
</Avatar>
```

> Может быть полезна функция [`getBadgeIconSizeByImageBaseSize`](/components/image-base#getbadgeiconsizebyimagebasesize).

### Готовый пресет бейджа

Подкомпонент `Avatar.BadgeWithPreset` предоставляет готовые пресеты `Avatar.Badge`.
При передаче в свойство `preset` значения `online` используется иконка `Icon12Circle`,
а при значении `online-mobile` иконка `Icon12OnlineMobile`.

```jsx
<Avatar src="https://avatars.githubusercontent.com/u/14944123?s=50" size={48}>
  <Avatar.BadgeWithPreset preset="online" />
</Avatar>
<Avatar src="https://avatars.githubusercontent.com/u/7431217?s=50" size={48}>
  <Avatar.BadgeWithPreset preset="online-mobile" />
</Avatar>
```

### Иконка-заглушка

На случай, если картинка не смогла загрузиться, будет отображаться иконка-заглушка.
Размер иконки-заглушки должен зависеть от размеров аватара.

```jsx
<Avatar fallbackIcon={<Icon3218CircleOutline />} />
```

> Может быть полезна функция [`getFallbackIconSizeByImageBaseSize`](/components/image-base#getfallbackiconsizebyimagebasesize).

### Наложение

```jsx
<Avatar src="https://avatars.githubusercontent.com/u/91548592?s=50">
  <Avatar.Overlay theme="dark" visibility="always">
    <Icon24Camera />
  </Avatar.Overlay>
</Avatar>
```

> Может быть полезна функция [`getOverlayIconSizeByImageBaseSize`](/components/image-base#getoverlayiconsizebyimagebasesize).

> Свойство `visibility` подкомпонента `Avatar.Overlay` по умолчанию зависит от наличия указателя на устройстве. На мобильных наложение показано всегда, на десктопах — только при наведении на аватар.

## Вспомогательные функции

### calcInitialsAvatarColor

Для динамического определения градиента под пользователя используйте функцию `calcInitialsAvatarColor`.
Она генерирует значение градиента по формуле `user_id % 6 + 1`.
Например, у пользователя с `user_id={106}` будет 5-й (`"l-blue"`) цвет градиента.

```jsx
import { calcInitialsAvatarColor } from '@vkontakte/vkui';

// userId определён где-то выше
<Avatar initials="ВК" gradientColor={calcInitialsAvatarColor(userId)} />;
```

## Особенности

Компонент поддерживает следующие возможности:

* автоматическая адаптация размера шрифта для инициалов;
* поддержка всех стандартных HTML-атрибутов `<img>`;
* сохранение пропорций изображения при изменении размеров.

## Свойства и методы \[#api]

### Avatar

| Свойство                    | Тип                                                                                                                                                   | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `elementTiming`             | `string`                                                                                                                                              | `-`          | Смотри [https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/elementtiming](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/elementtiming).                                                                                                                                                                                                                                                                                                                                                                |
| `fallbackIcon`              | `ReactElement<ImageBaseExpectedIconProps, string \| JSXElementConstructor<any>>`                                                                      | `-`          | Фолбек на случай, если картинка не прогрузилась.  > 📝 Нужный для `<ImageBase size={...} />` размер можно узнать из функции `getFallbackIconSizeByImageBaseSize()`.  > Предпочтительней использовать иконки из `@vkontakte/icons`.  > 📊️ Если вы хотите передать кастомную иконку, то следует именовать её по шаблону `Icon<size><name>`. Или же > чтобы в неё был передан параметр `width`. Тогда мы сможем выводить в консоль подсказку правильного ли размера вы > использовали иконку.  > ⚠️ Может перекрывать `children`. |
| `filter`                    | `Filter`                                                                                                                                              | `-`          | Пользовательское значения стиля filter. Подробнее можно почитать в [документации](https://developer.mozilla.org/ru/docs/Web/CSS/filter).  При передаче этого свойства `<img />` будет обёрнут в дополнительный контейнер.                                                                                                                                                                                                                                                                                                       |
| `getRef`                    | `Ref<HTMLImageElement>`                                                                                                                               | `-`          | **Deprecated**: Since 7.9.0. Будет удалено в v9. Используйте `slotProps={ img: { getRootRef: ... } }`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `getRootRef`                | `Ref<HTMLDivElement>`                                                                                                                                 | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `gradientColor`             | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| InitialsAvatarTextGradients \| "custom"`                                                                               | `-`          | Задаёт градиент для фона.  Если передано число, то оно будет сконвертировано в строчное представление цвета по следующей схеме:  1: 'red' 2: 'orange' 3: 'yellow' 4: 'green' 5: 'l-blue' 6: 'violet'.  > Если необходимо задать свой градиент, то используйте значение `"custom"` и определите цвет градиента либо через > свой класс в `className`, либо через `style={{ backgroundImage: "..." }}`.                                                                                                                           |
| `initials`                  | `string`                                                                                                                                              | `-`          | Инициалы пользователя.  > Note: Если аватарка не прогрузится, то пользователь увидит инициалы.  > ⚠️ Перебивает `fallbackIcon`.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `keepAspectRatio`           | `boolean`                                                                                                                                             | `-`          | Флаг для сохранения пропорций картинки. Для корректной работы необходимо задать размеры хотя бы одной стороны картинки.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `noBorder`                  | `boolean`                                                                                                                                             | `-`          | Отключает обводку.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `objectFit`                 | `ObjectFit`                                                                                                                                           | `-`          | Пользовательское значения стиля object-fit Подробнее можно почитать в [документации](https://developer.mozilla.org/ru/docs/Web/CSS/object-fit).                                                                                                                                                                                                                                                                                                                                                                                 |
| `objectPosition`            | `ObjectPosition<string \| number>`                                                                                                                    | `-`          | Пользовательское значения стиля object-position Подробнее можно почитать в [документации](https://developer.mozilla.org/ru/docs/Web/CSS/object-position).                                                                                                                                                                                                                                                                                                                                                                       |
| `ref`                       | `Ref<HTMLDivElement>`                                                                                                                                 | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `size`                      | `LiteralUnion<16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 56 \| 64 \| 72 \| 80 \| 88 \| 96, number>`                                        | `48`         | Задаёт размер картинки.  Используйте размеры заданные дизайн-системой `16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 56 \| 64 \| 72 \| 80 \| 88 \| 96`.  > ⚠️ Использование кастомного размера – это пограничный кейс.                                                                                                                                                                                                                                                                                                  |
| `slotProps`                 | `{ img?: (ClassAttributes<HTMLImageElement> & ImgHTMLAttributes<HTMLImageElement> & HasRootRef<HTMLImageElement> & HasDataAttribute); } \| undefined` | `-`          | Свойства, которые можно прокинуть внутрь компонента: - `img`: свойства для прокидывания в тег `<img>`;.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `withTransparentBackground` | `boolean`                                                                                                                                             | `-`          | Отключает фон, заданный по умолчанию. Полезен для отображения картинок с прозрачностью.                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### Avatar.Badge

| Свойство          | Тип                                                                              | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------- | -------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `background`      | `"stroke" \| "shadow"`                                                           | `-`          | Вид подложки под иконку.  - `"stroke"` – имитирует вырез (⚠️ если фон под компонентом динамический, то ожидайте баг). - `"shadow"` – добавляет небольшую тень (⚠️ если фон под компонентом динамический, то ожидайте баг).                                                                                                                                                                                                                                |
| `**children** \*` | `ReactElement<ImageBaseExpectedIconProps, string \| JSXElementConstructor<any>>` | `-`          | Принимает иконку.  > 📝 Нужный для `<ImageBase size={...} />` размер можно узнать из функции `getBadgeIconSizeByImageBaseSize()`.  > Предпочтительней использовать иконки из `@vkontakte/icons`.  > 📊️ Если вы хотите передать кастомную иконку, то следует именовать её по шаблону `Icon<size><name>`. Или же > чтобы в неё был передан параметр `width`. Тогда мы сможем выводить в консоль подсказку правильного ли размера вы > использовали иконку. |
| `getRootRef`      | `Ref<HTMLDivElement>`                                                            | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `ref`             | `Ref<HTMLDivElement>`                                                            | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

### Avatar.BadgeWithPreset

| Свойство     | Тип                           | По умолчанию | Описание                                                                               |
| ------------ | ----------------------------- | ------------ | -------------------------------------------------------------------------------------- |
| `getRootRef` | `Ref<HTMLDivElement>`         | `-`          |                                                                                        |
| `preset`     | `"online" \| "online-mobile"` | `online`     | Использует предзаданные настройки.  За каждым пресетом закреплена своя иконка и стили. |
| `ref`        | `Ref<HTMLDivElement>`         | `-`          |                                                                                        |

### Avatar.Overlay

| Свойство          | Тип                                                                                           | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `**children** \*` | `ReactNode \| ReactElement<ImageBaseExpectedIconProps, string \| JSXElementConstructor<any>>` | `-`          | Принимает иконку.   > 📝 Нужный для `<ImageBase size={...} />` размер можно узнать из функции `getOverlayIconSizeByImageBaseSize()`.  > Предпочтительней использовать иконки из `@vkontakte/icons`.  > 📊️ Если вы хотите передать кастомную иконку, то следует именовать её по шаблону `Icon<size><name>`. Или же > чтобы в неё был передан параметр `width`. Тогда мы сможем выводить в консоль подсказку правильного ли размера вы > использовали иконку. Содержимое.                                                                                                    |
| `className`       | `string`                                                                                      | `-`          | `className` для компонента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `getRootRef`      | `Ref<HTMLDivElement>`                                                                         | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `onClick`         | `MouseEventHandler<HTMLElement>`                                                              | `-`          | Обработчик взаимодействия с элементом. По умолчанию сам компонент является интерактивным элементом. Передав значение равное `'undefined'` или не передав этот параметр вовсе, можно отключить такое поведение, что дает возможность передавать отдельные интерактивные элементы в `children`.                                                                                                                                                                                                                                                                               |
| `ref`             | `Ref<HTMLDivElement>`                                                                         | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `theme`           | `"dark" \| "light"`                                                                           | `-`          | Задаёт тему оформления.  > По умолчанию берётся из параметра `appearance` в `ConfigProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `visibility`      | `"on-hover" \| "always"`                                                                      | `-`          | Определяет каким образом должен показываться оверлей.  - `"on-hover"` – на наведение указателя мыши. - `"always"` – всегда показывать.  > По умолчанию определяется в зависимости от того, есть ли у пользователя мышь или нет. > Определение просиходит с помощью двойного рендера, так что на устройствах без мыши > оверлей покажется не раньше второго рендера. > Если это критично (например при SSR), то старайтесь явно указывать значение `visibility`, либо используйте > [AdaptivityProvider](#/AdaptivityProvider) для того, чтобы явно определить `hasPointer`. |
