﻿---
description: Базовый компонент по работе с изображениями с добавлением возможности накладывать различные элементы поверх изображения.
tags: media
---

# ImageBase \[tag:component]

Базовый компонент по работе с изображениями, лежит в основе [`Avatar`](/components/avatar) и [`Image`](/components/image).
Наследует все свойства HTML-элемента `<img>` и добавляет возможность накладывать различные элементы поверх изображения.

```jsx
<ImageBase
  size={96}
  src="https://sun9-26.userapi.com/YZ5-1A6cVgL7g1opJGQIWg1Bl5ynfPi8p41SkQ/IYIUDqGkkBE.jpg"
/>
```

## Адаптивные размеры \[#sizes]

Задать размеры изображения можно через свойства `size` (если ширина и высота равны) или `widthSize` и `heightSize`
(если ширина и высота отличаются).

> Нативные свойства `width`/`height` задают размеры самого изображения.
> Чаще всего нужны `size` или `widthSize`/`heightSize` — они задают размеры всего контейнера с изображением.

Используйте предопределённые размеры (`16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 56 | 64 | 72 | 80 | 88 | 96`).

Пользовательские значения свойствам `size` или `widthSize`/`heightSize` задаются только числами,
либо строками с указанием пикселей (`33px`), другие единицы измерения не допускаются дизайн-системой
для сохранения возможности рассчитывать радиус скругления.

### Сохранение пропорций

С заданным свойством `keepAspectRatio` можно не указывать либо ширину, либо высоту картинки - оригинальные
соотношения сторон сохраняются.

Если вам необходимо растянуть изображение на всю ширину или высоту контейнера, то допускается `widthSize` или `heightSize`
указать `100%`.

```jsx
<ImageBase
  keepAspectRatio
  widthSize="200px"
  src="https://sun9-26.userapi.com/YZ5-1A6cVgL7g1opJGQIWg1Bl5ynfPi8p41SkQ/IYIUDqGkkBE.jpg"
/>
```

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

Добавляйте дополнительные элементы поверх изображения:

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

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

```jsx
<ImageBase size={96} fallbackIcon={<Icon3218CircleOutline />} />
```

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

### Индикатор

Индикатор в правом нижнем углу компонента:

```jsx
<ImageBase
  size={96}
  src="https://sun9-26.userapi.com/YZ5-1A6cVgL7g1opJGQIWg1Bl5ynfPi8p41SkQ/IYIUDqGkkBE.jpg"
>
  <ImageBase.Badge background="stroke">
    <Icon24StarCircleFillGreen />
  </ImageBase.Badge>
</ImageBase>
```

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

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

Перекрывающий картинку элемент задаётся через `Image.Overlay`:

```jsx
<ImageBase
  size={96}
  src="https://sun9-26.userapi.com/YZ5-1A6cVgL7g1opJGQIWg1Bl5ynfPi8p41SkQ/IYIUDqGkkBE.jpg"
>
  <ImageBase.Overlay visibility="always">
    <Icon24AddOutline />
  </ImageBase.Overlay>
</ImageBase>
```

Особенность компонента заключается в способе его отображения через свойство `visibility`.
Если оно явно не задано, то по умолчанию на устройствах с указателем (например, мышь) применяется `on-hover`,
позволяющее показывать наложение при наведении на картинку, на остальных устройствах (например, мобильные)
наложение показывается всегда.

С помощью свойства `theme` можно задать цвет наложения, по умолчанию наследуется тема приложения.

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

### Позиционированный компонент

Позиционированный компонент расположенный поверх изображения в произвольном месте задаётся `ImageBase.FloatElement`:

```jsx
<ImageBase
  size={96}
  src="https://sun9-26.userapi.com/YZ5-1A6cVgL7g1opJGQIWg1Bl5ynfPi8p41SkQ/IYIUDqGkkBE.jpg"
>
  <ImageBase.FloatElement placement="top-end" inlineIndent="xs" blockIndent="xs">
    <Button size="s" mode="primary" after={<Icon16MoreHorizontal />} />
  </ImageBase.FloatElement>
</ImageBase>
```

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

### getBadgeIconSizeByImageBaseSize

Размер иконки для бейджа необходимо подстраивать под разные значения свойства `size` компонента.
Например, для изображений размером `28x28` лучше смотрятся иконки бейджа размером `12x12`.
Дизайн-система уже определяет наилучшие размеры иконок, поэтому вместо
ручного подбора вы можете использовать функцию `getBadgeIconSizeByImageBaseSize` и на её основе реализовать
рендер иконки:

```jsx
import { ImageBaseContext, getBadgeIconSizeByImageBaseSize } from '@vkontakte/vkui';

// Убедитесь, что используете контекст в компоненте или хуке, который расположен ниже `ImageBase`.
const { size } = React.useContext(ImageBaseContext);
const iconSize = getBadgeIconSizeByImageBaseSize(size);
// ИЛИ если размер изображения статичный и всегда равен одному значению
const iconSize = getFallbackIconSizeByImageBaseSize(56);

// Теперь используйте iconSize для выбора иконки в нужном размере
```

### getOverlayIconSizeByImageBaseSize

Размер иконки для наложения необходимо подстраивать под разные значения свойства `size` компонента.
Например, для изображений размером `28x28` лучше смотрятся иконки наложения размером `20x20`.
Дизайн-система уже определяет наилучшие размеры иконок, поэтому вместо
ручного подбора вы можете использовать функцию `getOverlayIconSizeByImageBaseSize` и на её основе реализовать
рендер иконки:

```jsx
import { ImageBaseContext, getOverlayIconSizeByImageBaseSize } from '@vkontakte/vkui';

// Убедитесь, что используете контекст в компоненте или хуке, который расположен ниже `ImageBase`.
const { size } = React.useContext(ImageBaseContext);
const iconSize = getOverlayIconSizeByImageBaseSize(size);
// ИЛИ если размер изображения статичный и всегда равен одному значению
const iconSize = getFallbackIconSizeByImageBaseSize(56);

// Теперь используйте iconSize для выбора иконки в нужном размере
```

### getFallbackIconSizeByImageBaseSize

Размер иконки, которая будет отрисована, если изображение не удалось загрузить,
необходимо подстраивать под разные значения свойства `size` компонента.
Например, для изображений размером `28x28` лучше смотрятся иконки размером `20x20`.
Дизайн-система уже определяет наилучшие размеры иконок, поэтому вместо
ручного подбора вы можете использовать функцию `getFallbackIconSizeByImageBaseSize` и на её основе реализовать
рендер иконки:

```jsx
import { ImageBaseContext, getFallbackIconSizeByImageBaseSize } from '@vkontakte/vkui';

// Убедитесь, что используете контекст в компоненте или хуке, который расположен ниже `ImageBase`.
const { size } = React.useContext(ImageBaseContext);
const iconSize = getFallbackIconSizeByImageBaseSize(size);
// ИЛИ если размер изображения статичный и всегда равен одному значению
const iconSize = getFallbackIconSizeByImageBaseSize(56);

// Теперь используйте iconSize для выбора иконки в нужном размере
```

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

### ImageBase

| Свойство                    | Тип                                                                                                                                                   | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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>`                                                                                                                                 | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `heightSize`                | `string \| number`                                                                                                                                    | `-`          | Высота изображения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `keepAspectRatio`           | `boolean`                                                                                                                                             | `false`      | Флаг для сохранения пропорций картинки. Для корректной работы необходимо задать размеры хотя бы одной стороны картинки.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `noBorder`                  | `boolean`                                                                                                                                             | `false`      | Отключает обводку.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `objectFit`                 | `ObjectFit`                                                                                                                                           | `cover`      | Пользовательское значения стиля 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>`                                        | `-`          | Задаёт размер картинки.  Используйте размеры заданные дизайн-системой `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>`;.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `widthSize`                 | `string \| number`                                                                                                                                    | `-`          | Ширина изображения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `withTransparentBackground` | `boolean`                                                                                                                                             | `-`          | Отключает фон, заданный по умолчанию. Полезен для отображения картинок с прозрачностью.                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### ImageBase.Badge

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

### ImageBase.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`. |

### ImageBase.FloatElement

| Свойство           | Тип                       | По умолчанию | Описание                                                                                       |
| ------------------ | ------------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
| `blockIndent`      | `FloatElementIndentation` | `-`          | Отступ компонента от края контейнера по вертикали.                                             |
| `getRootRef`       | `Ref<HTMLDivElement>`     | `-`          |                                                                                                |
| `inlineIndent`     | `FloatElementIndentation` | `-`          | Отступ компонента от края контейнера по горизонтали.                                           |
| `**placement** \*` | `FloatElementPlacement`   | `-`          | Позиция компонента относительно родителя.                                                      |
| `ref`              | `Ref<HTMLDivElement>`     | `-`          |                                                                                                |
| `visibility`       | `"on-hover" \| "always"`  | `always`     | Режим отображения компонента:  - `"always"`: Всегда - `"on-hover"`: При наведении на картинку. |
