Для фотографии человека или логотипа компании в круглой рамке возьмите CdsAvatar, для интерфейсных пиктограмм — CdsIcon. Если пропорции нужно задать не картинке, а произвольному блоку — видео, карте, iframe — используйте CdsResponsive, а слайд-шоу из нескольких изображений соберёт CdsCarousel.

Анатомия

Первая схема — загруженное изображение: контейнер держит размеры и пропорции, внутри лежит тег img, а поверх — необязательный градиент. Вторая — то же место, пока файл не доехал: размытая заглушка из lazy-src и содержимое слота placeholder.

Storybook

Вариации

Размеры и пропорции

Минимум для показа картинки — src и одно ограничение размера: width, height, max-width или max-height. Свойство alt описывает изображение для читателей с экранными дикторами и попадает в aria-label контейнера.

Sandbox Storybook

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

<template>
  <CdsImage class="m-auto" src="/images/temp/wallpaper.webp" alt="Туман над лесным озером на рассвете" width="480" />
</template>

Свойство aspect-ratio резервирует место под изображение до того, как оно загрузится, — соседний контент не подпрыгнет. Значение принимается и дробью 16/9, и числом 1.7778. Без него компонент дождётся файла и возьмёт пропорции из его собственных размеров — а если файл не откроется, место под картинку схлопнется.

Sandbox Storybook

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

const ratios = ['16/9', '4/3', '1'];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <div v-for="ratio in ratios" :key="ratio" class="flex flex-col items-center gap-1">
      <CdsImage src="/images/temp/desert.webp" alt="Столовые горы на закате" width="200" :aspect-ratio="ratio" cover />
      <span class="text-100 text-content-secondary">aspect-ratio="{{ ratio }}"</span>
    </div>
  </div>
</template>

Заполнение контейнера

По умолчанию изображение вписывается в контейнер целиком (object-fit: contain) и оставляет поля, если пропорции не совпали. Свойство cover наоборот заполняет рамку и обрезает лишнее — так фотографии разного размера встают в ровную сетку.

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="bg-surface-secondary"
        src="/images/temp/ny.webp"
        alt="Люди идут по улице Нью-Йорка на закате"
        width="280"
        aspect-ratio="16/9"
      />
      <span class="text-100 text-content-secondary">По умолчанию — изображение видно целиком</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="bg-surface-secondary"
        src="/images/temp/ny.webp"
        alt="Люди идут по улице Нью-Йорка на закате"
        width="280"
        aspect-ratio="16/9"
        cover
      />
      <span class="text-100 text-content-secondary">cover — рамка заполнена, края обрезаны</span>
    </div>
  </div>
</template>

Свойство position задаёт, какую часть кадра оставить видимой при обрезке. Принимает любое значение object-position, включая пары вроде left top и проценты.

Sandbox Storybook

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

const positions = ['top', 'center', 'bottom'];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <div v-for="position in positions" :key="position" class="flex flex-col items-center gap-1">
      <CdsImage
        src="/images/temp/ny.webp"
        alt="Люди идут по улице Нью-Йорка на закате"
        width="220"
        aspect-ratio="16/9"
        :position="position"
        cover
      />
      <span class="text-100 text-content-secondary">position="{{ position }}"</span>
    </div>
  </div>
</template>

Загрузка

Изображение начинает грузиться, когда попадает в область видимости — вёрстка ниже первого экрана не тянет за собой десятки файлов. Пороги наблюдения настраиваются свойством options (опции IntersectionObserver), а eager отключает ожидание и грузит картинку сразу — так стоит делать с изображениями первого экрана.

Пока файл едет, компонент показывает lazy-src — миниатюру того же кадра, растянутую и размытую, — и содержимое слота placeholder. Свойство color задаёт цвет подложки под ними. О ходе загрузки сообщают события loadstart и load.

Sandbox Storybook

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

const pending = ref(true);

// Пока файл не доехал, вместо него показываются lazy-src и слот placeholder
const src = computed(() =>
  pending.value ? 'https://cdn.example.com/slow-image.webp' : '/images/temp/cyber-girl.webp'
);
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsButton variant="soft" color="brand" @click="pending = !pending">
      {{ pending ? 'Завершить загрузку' : 'Начать заново' }}
    </CdsButton>

    <CdsImage
      :src="src"
      lazy-src="/images/temp/thumbnail.jpg"
      alt="Девушка у панорамного окна с видом на ночной город"
      width="480"
      aspect-ratio="16/9"
      cover
    >
      <template #placeholder>
        <div class="flex h-full items-center justify-center">
          <CdsProgressCircle indeterminate />
        </div>
      </template>
    </CdsImage>
  </div>
</template>

Ошибка загрузки

Если файл не открылся, компонент показывает слот error и сообщает об этом событием error. Без слота на месте картинки останется placeholder — поэтому для ошибки лучше дать свою заглушку с понятным текстом.

Sandbox Storybook

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

<template>
  <CdsImage
    class="m-auto"
    src="https://cdn.example.com/broken.webp"
    alt="Схема расположения складов"
    width="360"
    aspect-ratio="16/9"
    cover
  >
    <template #error>
      <div class="flex h-full flex-col items-center justify-center gap-1 bg-surface-secondary text-content-secondary">
        <CdsIcon name="error" size="lg" />
        <span class="text-100">Изображение недоступно</span>
      </div>
    </template>
  </CdsImage>
</template>

Градиент

Свойство gradient кладёт поверх изображения CSS-градиент — значение передаётся как аргументы linear-gradient(). Обычно он нужен, чтобы текст поверх фотографии оставался читаемым на любом кадре.

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="items-end"
        src="/images/temp/villa.webp"
        alt="Вилла с бассейном в вечернем свете"
        width="280"
        aspect-ratio="16/9"
        cover
      >
        <p class="w-full p-2 text-200 text-content-on-dark">Вилла Роза, Синтра</p>
      </CdsImage>
      <span class="text-100 text-content-secondary">Без градиента</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="items-end"
        src="/images/temp/villa.webp"
        alt="Вилла с бассейном в вечернем свете"
        width="280"
        aspect-ratio="16/9"
        gradient="to top, rgba(0, 0, 0, 0.75), transparent 55%"
        cover
      >
        <p class="w-full p-2 text-200 text-content-on-dark">Вилла Роза, Синтра</p>
      </CdsImage>
      <span class="text-100 text-content-secondary">С градиентом</span>
    </div>
  </div>
</template>

Контент поверх изображения

Слот по умолчанию рендерится над изображением и растягивается на весь контейнер: внутрь можно положить подпись, тег, кнопку. Раскладку задавайте утилитами на самом компоненте (items-end, justify-center) или через content-class.

Sandbox Storybook

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

<template>
  <CdsImage
    class="m-auto"
    src="/images/temp/cat.webp"
    alt="Кот с разноцветной шерстью"
    width="280"
    aspect-ratio="1"
    gradient="to top, rgba(0, 0, 0, 0.7), transparent 45%"
    cover
  >
    <div class="flex h-full flex-col items-start justify-between p-2">
      <CdsTag color="green" size="sm">Новинка</CdsTag>
      <span class="text-200 text-content-on-dark">Радужный кот, холст, 40 × 60</span>
    </div>
  </CdsImage>
</template>

Адаптивные источники

Свойства srcset и sizes попадают прямо в тег img — браузер сам выберет файл под плотность пикселей и ширину места. Когда для узкого экрана нужен не просто файл поменьше, а другой кадр, добавьте элементы <source> в слот sources: компонент завернёт изображение в <picture>. Сузьте окно — в примере широкая панорама сменится вертикальным кадром.

Sandbox Storybook

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

<template>
  <CdsImage
    class="m-auto"
    src="/images/temp/city.webp"
    alt="Панорама города на закате"
    width="100%"
    max-width="560"
    aspect-ratio="16/9"
    cover
  >
    <template #sources>
      <source media="(max-width: 700px)" srcset="/images/temp/ny.webp" />
    </template>
  </CdsImage>
</template>

Слоты

Слот	Описание
default	Контент поверх изображения
placeholder	Что показывать, пока изображение грузится
error	Что показывать, если изображение не загрузилось
sources	Элементы <source>; оборачивает изображение в <picture>

Рекомендации

Storybook

Сценарии использования

Карточки каталога

Обложки объявлений приходят из разных источников и почти никогда не совпадают по размеру. Общий aspect-ratio и cover приводят их к одной рамке, color держит нейтральную подложку, пока файл грузится, а слот по умолчанию оставляет тег в углу обложки.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardItem,
  CdsCardSubtitle,
  CdsCardTitle,
  CdsImage,
  CdsTag
} from '@central-design-system/components';

const listings = [
  {
    id: 'villa',
    src: '/images/temp/villa.webp',
    alt: 'Вилла с бассейном и садом на закате',
    tag: 'Хит',
    title: 'Вилла с бассейном',
    subtitle: 'Португалия, Синтра · 6 гостей',
    price: '18 400 ₽ за ночь'
  },
  {
    id: 'jungle',
    src: '/images/temp/airbnb.webp',
    alt: 'Деревянный дом в джунглях рядом с водопадом',
    tag: 'Новинка',
    title: 'Дом у водопада',
    subtitle: 'Бали, Убуд · 4 гостя',
    price: '9 900 ₽ за ночь'
  }
];
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsCard v-for="listing in listings" :key="listing.id" width="300">
      <CdsImage
        class="items-start"
        :src="listing.src"
        :alt="listing.alt"
        aspect-ratio="4/3"
        color="surface-secondary"
        cover
      >
        <CdsTag class="m-2" color="green" size="sm">{{ listing.tag }}</CdsTag>
      </CdsImage>

      <CdsCardItem>
        <CdsCardTitle>{{ listing.title }}</CdsCardTitle>
        <CdsCardSubtitle>{{ listing.subtitle }}</CdsCardSubtitle>
      </CdsCardItem>

      <CdsCardActions class="justify-between">
        <span class="text-200 text-content-primary">{{ listing.price }}</span>
        <CdsButton size="sm" text="Забронировать" />
      </CdsCardActions>
    </CdsCard>
  </div>
</template>

Обложка страницы

Широкая шапка с текстом поверх фотографии: height задаёт высоту полосы, cover и position кадрируют снимок под неё, gradient затемняет низ, чтобы заголовок и кнопка читались. Такой картинке нужен eager — она на первом экране, и ждать появления в области видимости ей незачем.

Sandbox Storybook

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

<template>
  <CdsImage
    class="items-end"
    src="/images/temp/wallpaper.webp"
    alt="Туман над лесным озером на рассвете"
    width="100%"
    height="280"
    gradient="to top, rgba(0, 0, 0, 0.8), rgba(0, 0, 0, 0.1) 70%"
    position="center"
    eager
    cover
  >
    <div class="flex w-full flex-col items-start gap-2 p-4">
      <p class="text-500 text-content-on-dark">Маршруты выходного дня</p>
      <p class="max-w-md text-200 text-content-on-dark opacity-80">
        Двенадцать озёр в двух часах езды от города — с картами, точками старта и списком снаряжения.
      </p>
      <CdsButton variant="solid" color="inverse" text="Открыть подборку" />
    </div>
  </CdsImage>
</template>

Галерея с превью

Клик по миниатюре меняет src большого изображения. Миниатюры получают общий aspect-ratio и cover, поэтому ряд остаётся ровным, а color держит подложку большого кадра, пока новый файл грузится. Если кадры нужно ещё и листать — стрелками или свайпом — возьмите готовый сценарий «Галерея с миниатюрами» у CdsCarousel.

Sandbox Storybook

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

const photos = [
  { src: '/images/temp/villa.webp', alt: 'Вилла с бассейном и садом на закате' },
  { src: '/images/temp/airbnb.webp', alt: 'Деревянный дом в джунглях рядом с водопадом' },
  { src: '/images/temp/wallpaper.webp', alt: 'Туман над лесным озером на рассвете' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Человек в скафандре под звёздным небом' }
];

const active = ref(0);
const current = computed(() => photos[active.value]);
</script>

<template>
  <div class="m-auto flex w-full max-w-[560px] flex-col gap-2">
    <CdsImage :src="current.src" :alt="current.alt" color="surface-secondary" width="100%" aspect-ratio="16/9" cover />

    <div class="flex flex-wrap gap-2">
      <button
        v-for="(photo, index) in photos"
        :key="photo.src"
        type="button"
        class="cursor-pointer overflow-hidden rounded-200 border-2"
        :class="index === active ? 'border-brand-primary' : 'border-transparent'"
        :aria-label="photo.alt"
        :aria-current="index === active"
        @click="active = index"
      >
        <CdsImage :src="photo.src" alt="" width="88" aspect-ratio="1" cover />
      </button>
    </div>
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
absolute	boolean | undefined	—	Позиционирует изображение как position: absolute, заполняя родителя.
alt	string | undefined	—	Альтернативный текст изображения (атрибут alt).
aspectRatio	string | number | undefined	—	Соотношение сторон контента. Например 1.7778 (16/9) или '4/3'.
color	string | undefined	—	Цвет фона-плейсхолдера, отображаемого во время загрузки.
contentClass	any	—	CSS-класс, применяемый к обёртке контента.
cover	boolean | undefined	—	Масштабирует изображение, чтобы оно полностью закрывало контейнер (object-fit: cover).
crossorigin	"" | "anonymous" | "use-credentials" | undefined	—	Значение атрибута crossorigin.
draggable	boolean | "true" | "false" | undefined	—	Управляет возможностью перетаскивания изображения (атрибут draggable).
eager	boolean | undefined	—	Принудительно загружает изображение сразу, не дожидаясь появления в области видимости.
gradient	string | undefined	—	CSS-градиент, накладываемый поверх изображения. Например 'to top, rgba(0,0,0,.4), transparent'.
height	string | number | undefined	—	Высота компонента
imageClass	any	—	CSS-класс, применяемый к внутреннему элементу <img>.
inline	boolean | undefined	—	Отображает компонент как inline-блок (inline-flex) вместо блочного.
lazySrc	string | undefined	—	Источник изображения-заглушки низкого качества, показываемого до загрузки основного.
maxHeight	string | number | undefined	—	Максимальная высота компонента
maxWidth	string | number | undefined	—	Максимальная ширина компонента
minHeight	string | number | undefined	—	Минимальная высота компонента
minWidth	string | number | undefined	—	Минимальная ширина компонента
options	IntersectionObserverInit | undefined	{}	Опции IntersectionObserver для ленивой загрузки.
position	string | undefined	—	Значение object-position для позиционирования изображения внутри контейнера.
referrerpolicy	"origin" | "no-referrer" | "no-referrer-when-downgrade" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | undefined	—	Значение атрибута referrerpolicy.
sizes	string | undefined	—	Значение атрибута sizes для адаптивных изображений.
src	string | CdsImageSrcObject | undefined	''	Источник изображения. Строка или объект с src/srcset/lazySrc/aspect.
srcset	string | undefined	—	Набор источников изображения для разных разрешений (атрибут srcset).
theme	string | undefined	—	Тема компонента
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	'fade-transition'	Анимация перехода
width	string | number | undefined	—	Ширина компонента

События

Имя	Тип	Описание
error	[value: string | undefined]	Срабатывает при ошибке загрузки изображения.
load	[value: string | undefined]	Срабатывает после успешной загрузки изображения.
loadstart	[value: string | undefined]	Срабатывает в начале загрузки изображения.

Слоты

Имя	Тип	Описание
default	any	Контент, отображаемый поверх изображения.
error	any	Содержимое, отображаемое при ошибке загрузки изображения.
placeholder	any	Содержимое, отображаемое во время загрузки изображения.
sources	any	Дополнительные элементы <source> для тега <picture>.

Exposed

Имя	Тип	Описание
currentSrc	string	Фактический адрес загруженного изображения — с учётом srcset и выбранной браузером плотности.
image	HTMLImageElement | undefined	Ссылка на DOM-элемент img.
naturalHeight	number | undefined	Собственная высота загруженного изображения в пикселях.
naturalWidth	number | undefined	Собственная ширина загруженного изображения в пикселях.
state	"error" | "loading" | "idle" | "loaded"	Состояние загрузки изображения: ожидание, загрузка, успех или ошибка.