﻿---
description: Компонент для отображения изображений с поддержкой адаптивных размеров, скруглений и позиционированных элементов.
tags: media
---

# Image \[tag:component]

Компонент для отображения изображений с поддержкой адаптивных размеров, скруглений и позиционированных элементов.
Наследует все свойства HTML-элемента `<img>`. Главное отличие от `ImageBase` заключается в поддержке
скруглений, определённых дизайн-системой и позиционирование индикаторов в зависимости от размеров.

```jsx
<Image size={96} src="https://sun9-51.userapi.com/c857024/v857024436/f927/rG9fac2cuac.jpg" />
```

## Адаптивные размеры

Справедливы все рекомендации, что и для [`ImageBase`](/components/image-base#sizes).

## Скругления

Контролируйте радиус скругления углов:

### Единое скругление

```jsx
<Image
  size={96}
  borderRadius="m"
  src="https://sun9-51.userapi.com/c857024/v857024436/f927/rG9fac2cuac.jpg"
/>
```

### Индивидуальные углы

```jsx
<Image
  size={64}
  borderStartStartRadius="l"
  borderEndEndRadius="l"
  src="https://sun9-51.userapi.com/c857024/v857024436/f927/rG9fac2cuac.jpg"
/>
```

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

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

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

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

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

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

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

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

```jsx
<Image src="https://sun9-51.userapi.com/c857024/v857024436/f927/rG9fac2cuac.jpg">
  <Image.Badge background="stroke">
    <Icon20PrivacyCircleFillRed />
  </Image.Badge>
</Image>
```

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

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

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

```jsx
<Image src="https://sun9-51.userapi.com/c857024/v857024436/f927/rG9fac2cuac.jpg">
  <Image.Overlay theme="dark" visibility="always">
    <Icon24AddOutline />
  </Image.Overlay>
</Image>
```

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

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

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

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

```jsx
<Image size={96} src="https://sun9-51.userapi.com/c857024/v857024436/f927/rG9fac2cuac.jpg">
  <Image.FloatElement placement="top-end" inlineIndent="xs" blockIndent="xs">
    <Button size="s" mode="primary" after={<Icon16MoreHorizontal />} />
  </Image.FloatElement>
</Image>
```

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

### Image

| Свойство                    | Тип                                                                                                                                                   | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `borderEndEndRadius`        | `"s" \| "m" \| "l"`                                                                                                                                   | `-`          | Размер закругления угла между сторонами конца блока и строки.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `borderEndStartRadius`      | `"s" \| "m" \| "l"`                                                                                                                                   | `-`          | Размер закругления угла между стороной конца блока и стороной начала строки.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `borderRadius`              | `"s" \| "m" \| "l"`                                                                                                                                   | `m`          | Размер закругления.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `borderStartEndRadius`      | `"s" \| "m" \| "l"`                                                                                                                                   | `-`          | Размер закругления угла между стороной начала блока и стороной конца строки.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `borderStartStartRadius`    | `"s" \| "m" \| "l"`                                                                                                                                   | `-`          | Размер закругления угла между сторонами начала блока и строки.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `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`                                                                                                                                             | `-`          | Флаг для сохранения пропорций картинки. Для корректной работы необходимо задать размеры хотя бы одной стороны картинки.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `noBorder`                  | `boolean`                                                                                                                                             | `-`          | Отключает обводку.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `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>`                                        | `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>`;.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `widthSize`                 | `string \| number`                                                                                                                                    | `-`          | Ширина изображения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `withTransparentBackground` | `boolean`                                                                                                                                             | `-`          | Отключает фон, заданный по умолчанию. Полезен для отображения картинок с прозрачностью.                                                                                                                                                                                                                                                                                                                                                                                                                                         |

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

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

### Image.FloatElement

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