For a photo of a person or a company logo in a round frame take CdsAvatar, for interface pictograms — CdsIcon. If the proportions have to be set not for a picture but for an arbitrary block — a video, a map, an iframe — use CdsResponsive, and a slideshow of several images is assembled by CdsCarousel.

Anatomy

The first diagram is a loaded image: the container holds the size and the proportions, the img tag sits inside, and an optional gradient lies on top. The second one is the same place while the file has not arrived yet: a blurred placeholder from lazy-src and the content of the placeholder slot.

Storybook

Variations

Size and proportions

The minimum needed to show a picture is src and one size constraint: width, height, max-width or max-height. The alt prop describes the image for readers with screen readers and goes into the aria-label of the container.

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>

The aspect-ratio prop reserves the space for the image before it loads — the neighboring content will not jump. The value is accepted both as the fraction 16/9 and as the number 1.7778. Without it the component waits for the file and takes the proportions from its own dimensions — and if the file fails to open, the space for the picture collapses.

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>

Filling the container

By default the image fits into the container as a whole (object-fit: contain) and leaves margins when the proportions do not match. The cover prop does the opposite: it fills the frame and crops the excess — this way photos of different sizes line up into an even grid.

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>

The position prop sets which part of the frame stays visible when cropping. It accepts any object-position value, including pairs like left top and percentages.

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>

Loading

The image starts loading when it enters the viewport — markup below the fold does not drag dozens of files along with it. The observation thresholds are configured by the options prop (the IntersectionObserver options), and eager turns the waiting off and loads the picture right away — which is what you should do with the images of the first screen.

While the file is on its way, the component shows lazy-src — a thumbnail of the same frame, stretched and blurred — and the content of the placeholder slot. The color prop sets the color of the backdrop under them. The loadstart and load events report the progress of the loading.

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>

Loading error

If the file failed to open, the component shows the error slot and reports it with the error event. Without that slot the placeholder stays in place of the picture — so for an error it is better to give your own fallback with a clear text.

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

The gradient prop lays a CSS gradient over the image — the value is passed as the arguments of linear-gradient(). Usually you need it to keep the text over a photo readable on any frame.

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>

Content over the image

The default slot renders above the image and stretches over the whole container: you can put a caption, a tag or a button inside. Set the layout with utilities on the component itself (items-end, justify-center) or through 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>

Responsive sources

The srcset and sizes props go straight into the img tag — the browser picks the file for the pixel density and the width of the place itself. When a narrow screen needs not just a smaller file but a different frame, add <source> elements into the sources slot: the component wraps the image into <picture>. Narrow the window — in the example the wide panorama gives way to a vertical frame.

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>

Slots

Slot	Description
default	Content over the image
placeholder	What to show while the image is loading
error	What to show when the image failed to load
sources	<source> elements; wraps the image into <picture>

Guidelines

Storybook

Scenarios

Catalog cards

Listing covers come from different sources and almost never match in size. A shared aspect-ratio and cover bring them to one frame, color holds a neutral backdrop while the file is loading, and the default slot leaves a tag in the corner of the cover.

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>

Page cover

A wide header with text over a photo: height sets the height of the band, cover and position crop the shot to fit it, and gradient darkens the bottom so that the title and the button stay readable. Such a picture needs eager — it is on the first screen and has no reason to wait for the viewport.

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>

Gallery with previews

A click on a thumbnail changes the src of the large image. The thumbnails get a shared aspect-ratio and cover, so the row stays even, and color holds the backdrop of the large frame while the new file is loading. If the frames also have to be flipped — with arrows or a swipe — take the ready-made “Gallery with thumbnails” scenario of 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

Props

Name	Type	Default	Description
absolute	boolean | undefined	—	Positions the image with position: absolute, filling its parent.
alt	string | undefined	—	Alternative text of the image (the alt attribute).
aspectRatio	string | number | undefined	—	Aspect ratio of the content. For example 1.7778 (16/9) or '4/3'.
color	string | undefined	—	Background color of the placeholder shown while loading.
contentClass	any	—	CSS class applied to the content wrapper.
cover	boolean | undefined	—	Scales the image so that it covers the whole container (object-fit: cover).
crossorigin	"" | "anonymous" | "use-credentials" | undefined	—	Value of the crossorigin attribute.
draggable	boolean | "true" | "false" | undefined	—	Controls whether the image can be dragged (the draggable attribute).
eager	boolean | undefined	—	Loads the image immediately instead of waiting for it to enter the viewport.
gradient	string | undefined	—	CSS gradient laid over the image. For example 'to top, rgba(0,0,0,.4), transparent'.
height	string | number | undefined	—	Component height
imageClass	any	—	CSS class applied to the inner <img> element.
inline	boolean | undefined	—	Renders the component as an inline block (inline-flex) instead of a block one.
lazySrc	string | undefined	—	Source of the low-quality placeholder image shown until the main one loads.
maxHeight	string | number | undefined	—	Maximum component height
maxWidth	string | number | undefined	—	Maximum component width
minHeight	string | number | undefined	—	Minimum component height
minWidth	string | number | undefined	—	Minimum component width
options	IntersectionObserverInit | undefined	{}	IntersectionObserver options for lazy loading.
position	string | undefined	—	Value of object-position that places the image inside the container.
referrerpolicy	"origin" | "no-referrer" | "no-referrer-when-downgrade" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | undefined	—	Value of the referrerpolicy attribute.
sizes	string | undefined	—	Value of the sizes attribute for responsive images.
src	string | CdsImageSrcObject | undefined	''	Image source. A string or an object with src/srcset/lazySrc/aspect.
srcset	string | undefined	—	Set of image sources for different resolutions (the srcset attribute).
theme	string | undefined	—	Component theme
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	'fade-transition'	Transition animation
width	string | number | undefined	—	Component width

Events

Name	Type	Description
error	[value: string | undefined]	Fires when the image fails to load.
load	[value: string | undefined]	Fires after the image has loaded successfully.
loadstart	[value: string | undefined]	Fires when the image starts loading.

Slots

Name	Type	Description
default	any	Content shown over the image.
error	any	Content shown when the image fails to load.
placeholder	any	Content shown while the image is loading.
sources	any	Extra <source> elements for the <picture> tag.

Exposed

Name	Type	Description
currentSrc	string	Actual address of the loaded image — taking srcset and the density chosen by the browser into account.
image	HTMLImageElement | undefined	Reference to the img DOM element.
naturalHeight	number | undefined	Natural height of the loaded image in pixels.
naturalWidth	number | undefined	Natural width of the loaded image in pixels.
state	"error" | "loading" | "idle" | "loaded"	Loading state of the image: idle, loading, success or error.