To switch content without delimiters and autoplay, take CdsSlideView — the carousel is built on top of it; for a single image take CdsImage.

Anatomy

A carousel is made of slides, navigation arrows, delimiter dots and an optional progress bar. Arrows and dots loop around: the first slide follows the last one.

Storybook

Variations

Images

CdsCarouselItem combines a slide and CdsImage — pass it any image prop: src, alt, cover, gradient. The height prop sets the height of the carousel (500 by default).

Sandbox Storybook

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

const slide = ref(0);

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/ny.webp', alt: 'Улицы Нью-Йорка' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel v-model="slide" height="360" class="m-auto max-w-[640px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
  </CdsCarousel>
</template>

Custom content

A slide does not have to be an image: put any markup into the slot of CdsCarouselItem and it stretches over the whole frame.

Sandbox Storybook

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

const slides = [
  { text: 'Первый слайд', class: 'bg-brand-primary' },
  { text: 'Второй слайд', class: 'bg-status-progress-fill' },
  { text: 'Третий слайд', class: 'bg-surface-inverse' }
];
</script>

<template>
  <CdsCarousel height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="slide in slides" :key="slide.text">
      <div class="flex h-full items-center justify-center text-500 text-content-on-dark" :class="slide.class">
        {{ slide.text }}
      </div>
    </CdsCarouselItem>
  </CdsCarousel>
</template>

Autoplay

The cycle prop flips the slides automatically, interval sets the pause in milliseconds (6000 by default). The timer restarts after a manual switch, so the reader always has time to finish looking at a slide.

Sandbox Storybook

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

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel cycle :interval="3000" height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
  </CdsCarousel>
</template>

Progress

The progress prop adds a position bar at the bottom of the carousel. A string value sets its color — any of the tokens that CdsProgressBar accepts.

Sandbox Storybook

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

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsCarousel progress hide-delimiters height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">progress</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsCarousel progress="brand-primary" hide-delimiters height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">progress="brand-primary"</span>
    </div>
  </div>
</template>

Delimiters

Props control the navigation dots: hide-delimiters removes them completely, hide-delimiter-background removes only the backdrop, vertical-delimiters (left / right) puts the dots vertically along the edge, and delimiter-icon changes the dot icon.

Sandbox Storybook

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

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsCarousel hide-delimiter-background height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">hide-delimiter-background</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsCarousel vertical-delimiters="right" hide-delimiter-background height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">vertical-delimiters="right"</span>
    </div>
  </div>
</template>

The item slot replaces a dot with your own element: it receives the ready-made delimiter props (click handler, aria-label, active class) and the group item itself — all that is left is to bind them with v-bind.

Sandbox Storybook

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

const slide = ref(0);

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel v-model="slide" height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />

    <template #item="{ props: itemProps, item }">
      <CdsButton
        v-bind="itemProps"
        size="sm"
        variant="solid"
        :color="slide === item.value ? 'brand' : 'inverse'"
        :text="String(Number(item.value) + 1)"
      />
    </template>
  </CdsCarousel>
</template>

Arrows

The arrow props are inherited from CdsSlideView: show-arrows="hover" shows them on hover only, :show-arrows="false" removes them completely, prev-icon / next-icon change the icons, and the prev / next slots replace the buttons themselves.

Sandbox Storybook

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

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel show-arrows="hover" height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
  </CdsCarousel>
</template>

Guidelines

Storybook

Scenarios

Promo banners

The classic banner rotation: cycle with a 5 second interval flips the slides on its own, progress shows when the next one comes. The text and the button live in the slide slot, and the gradient from CdsImage darkens the top of the frame beneath them — so they stay readable on any image.

Sandbox Storybook

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

const banners = [
  {
    src: '/images/temp/city.webp',
    alt: 'Вечерний город',
    title: 'Городские туры выходного дня',
    text: 'Скидка 20% на все маршруты до конца месяца'
  },
  {
    src: '/images/temp/villa.webp',
    alt: 'Вилла с бассейном',
    title: 'Виллы у моря',
    text: 'Раннее бронирование лета — уже открыто'
  },
  {
    src: '/images/temp/desert.webp',
    alt: 'Столовые горы на закате',
    title: 'Экспедиции в пустыню',
    text: 'Небольшие группы, опытные гиды'
  }
];
</script>

<template>
  <CdsCarousel cycle :interval="5000" progress height="280" class="m-auto max-w-[640px]">
    <CdsCarouselItem
      v-for="banner in banners"
      :key="banner.src"
      :src="banner.src"
      :alt="banner.alt"
      gradient="to bottom, rgba(0, 0, 0, 0.7), transparent 60%"
      cover
    >
      <div class="flex w-full items-start justify-between gap-2 p-4">
        <div>
          <p class="text-500 font-bold text-content-on-dark">{{ banner.title }}</p>
          <p class="text-200 text-content-on-dark">{{ banner.text }}</p>
        </div>
        <CdsButton text="Подробнее" size="sm" />
      </div>
    </CdsCarouselItem>
  </CdsCarousel>
</template>

Gallery with thumbnails

The dots are replaced by thumbnails: hide-delimiters removes the built-in delimiters, and a click on a thumbnail changes v-model. The counter next to it reads the same v-model — the carousel, the thumbnails and the counter always stay in sync.

Sandbox Storybook

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

const slide = ref(0);

const photos = [
  { src: '/images/temp/villa.webp', alt: 'Вилла с бассейном' },
  { src: '/images/temp/airbnb.webp', alt: 'Гостиная с камином' },
  { src: '/images/temp/ny.webp', alt: 'Вид на город из окна' },
  { src: '/images/temp/wallpaper.webp', alt: 'Озеро рядом с виллой' }
];
</script>

<template>
  <div class="m-auto flex w-[480px] flex-col gap-2">
    <CdsCarousel v-model="slide" hide-delimiters height="280">
      <CdsCarouselItem v-for="photo in photos" :key="photo.src" :src="photo.src" :alt="photo.alt" cover />
    </CdsCarousel>

    <div class="flex items-center justify-between">
      <div class="flex gap-1">
        <button
          v-for="(photo, index) in photos"
          :key="photo.src"
          type="button"
          class="cursor-pointer overflow-hidden rounded-100 border-2 border-solid p-0"
          :class="slide === index ? 'border-brand-primary' : 'border-transparent'"
          :aria-label="photo.alt"
          @click="slide = index"
        >
          <CdsImage :src="photo.src" :alt="''" width="56" height="42" cover />
        </button>
      </div>
      <span class="text-200 text-content-secondary">{{ slide + 1 }} / {{ photos.length }}</span>
    </div>
  </div>
</template>

Vertical feed

A stories feed in the spirit of social networks: direction="vertical" flips the frames top to bottom, vertical-arrows="left" and vertical-delimiters="right" pull the arrows and the dots apart to the side edges and free up the frame. The author card and the counter sit in an absolute layer above the carousel: pointer-events-none lets clicks through to the arrows, and a transition keyed by v-model swaps the card together with the slide.

Sandbox Storybook

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

const slide = ref(0);

const stories = [
  {
    src: '/images/temp/space.webp',
    alt: 'Звёздное небо',
    author: 'Марина Соколова',
    followers: '31 тыс. подписчиков',
    avatar: 'https://i.pravatar.cc/80?img=47'
  },
  {
    src: '/images/temp/desert.webp',
    alt: 'Столовые горы на закате',
    author: 'Григорий Ковалёв',
    followers: '412 подписчиков',
    avatar: 'https://i.pravatar.cc/80?img=59'
  },
  {
    src: '/images/temp/city.webp',
    alt: 'Вечерний город',
    author: 'Эмма Королёва',
    followers: '521 подписчик',
    avatar: 'https://i.pravatar.cc/80?img=44'
  },
  {
    src: '/images/temp/cat.webp',
    alt: 'Рыжий кот',
    author: 'Антон Макаров',
    followers: '6 тыс. подписчиков',
    avatar: 'https://i.pravatar.cc/80?img=68'
  }
];

const current = computed(() => stories[slide.value]);
</script>

<template>
  <div class="relative m-auto max-w-[560px] overflow-hidden rounded-200">
    <CdsCarousel
      v-model="slide"
      direction="vertical"
      vertical-arrows="left"
      vertical-delimiters="right"
      hide-delimiter-background
      progress
      height="360"
    >
      <CdsCarouselItem v-for="story in stories" :key="story.src" :src="story.src" :alt="story.alt" cover />
    </CdsCarousel>

    <div class="pointer-events-none absolute inset-0 z-10 flex flex-col items-center justify-between py-4">
      <Transition name="jump-transition-right" mode="out-in" appear>
        <div :key="slide" class="flex items-center gap-2 rounded-full bg-surface-primary p-1 pr-4">
          <CdsAvatar :image="current.avatar" />
          <div>
            <p class="text-200 font-bold text-content-primary">{{ current.author }}</p>
            <p class="text-100 text-content-secondary">{{ current.followers }}</p>
          </div>
        </div>
      </Transition>

      <CdsTag :text="`${slide + 1} / ${stories.length}`" size="sm" />
    </div>
  </div>
</template>

Onboarding

Product introduction steps: the arrows are off (:show-arrows="false"), the movement is driven by the "Back" and "Next" buttons through v-model. On the last step "Next" turns into a call to action.

Sandbox Storybook

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

const slide = ref(0);

const steps = [
  { icon: 'search', title: 'Ищите быстрее', text: 'Единый поиск по проектам, файлам и обсуждениям.' },
  {
    icon: 'notification',
    title: 'Ничего не пропускайте',
    text: 'Уведомления о важных событиях — там, где вам удобно.'
  },
  { icon: 'trophy', title: 'Отмечайте прогресс', text: 'Дашборд покажет, как продвигается работа команды.' }
];

const isLast = computed(() => slide.value === steps.length - 1);
</script>

<template>
  <div class="m-auto flex w-[420px] flex-col gap-2">
    <CdsCarousel v-model="slide" :show-arrows="false" hide-delimiter-background height="220">
      <CdsCarouselItem v-for="step in steps" :key="step.title">
        <div class="flex h-full flex-col items-center justify-center gap-2 bg-surface-secondary px-8 text-center">
          <CdsIcon :icon="step.icon" :size="32" />
          <p class="text-400 font-bold text-content-primary">{{ step.title }}</p>
          <p class="text-200 text-content-secondary">{{ step.text }}</p>
        </div>
      </CdsCarouselItem>
    </CdsCarousel>

    <div class="flex justify-between">
      <CdsButton variant="soft" color="neutral" text="Назад" :disabled="slide === 0" @click="slide -= 1" />
      <CdsButton v-if="!isLast" text="Далее" @click="slide += 1" />
      <CdsButton v-else text="Начать работу" @click="slide = 0" />
    </div>
  </div>
</template>

API

CdsCarousel

Props

Name	Type	Default	Description
color	string | undefined	—	Color of the active delimiter and of the progress bar
continuous	boolean | undefined	true	Loops the navigation: from the last slide you move to the first one and back
crossfade	boolean | undefined	—	Slides change with a smooth crossfade instead of a shift
cycle	boolean | undefined	—	Flips the slides automatically after the given interval
delimiterIcon	IconValue | undefined	'dot'	Icon of the delimiter (navigation dot)
direction	"horizontal" | "vertical" | undefined	'horizontal'	Switches the component between horizontal and vertical layout.
disabled	boolean | null | undefined	null	Disabled state
height	string | number | undefined	500	Height of the carousel
hideDelimiterBackground	boolean | undefined	—	Hides the backdrop under the delimiters
hideDelimiters	boolean | undefined	—	Hides the delimiters (navigation dots)
interval	string | number | undefined	6000	Autoplay interval in milliseconds (when cycle is on)
mandatory	boolean | "force" | undefined	'force'	Requires at least one item to stay selected
max	number | undefined	—	Maximum number of items that can be selected
modelValue	any	—	Value of the selected items of the group
multiple	boolean | undefined	—	Allows selecting several items at once
nextIcon	IconValue | undefined	'chevron-right'	Icon of the button that moves to the next slide
prevIcon	IconValue | undefined	'chevron-left'	Icon of the button that moves to the previous slide
progress	string | boolean | undefined	—	Shows the progress bar of the current slide. A string sets the color of the bar
required	boolean | "force" | undefined	—	Requires at least one item to stay selected
reverse	boolean | undefined	—	Inverts the direction of the transition animation between slides
selectedClass	string | undefined	—	CSS class applied in the selected state
showArrows	string | boolean | undefined	true	Shows the navigation arrows. 'hover' — only while the pointer is over the component
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
theme	string | undefined	—	Component theme
touch	boolean | TouchHandlers | undefined	—	Controls swipe navigation: false turns the gestures off, an object sets your own touch handlers
transitionDuration	number | undefined	—	Duration of the transition animation between slides, in milliseconds
verticalArrows	boolean | "left" | "right" | undefined	—	Places the navigation arrows vertically: 'left' or 'right' — the side, true — the default side
verticalDelimiters	boolean | "left" | "right" | undefined	—	Vertical placement of the delimiters: left, right or true (left)

Events

Name	Type	Description
update:modelValue	[]	Fires when the active slide changes.

Slots

Name	Type	Description
default	{ group: GroupProvide; }	Slides. The slot props carry the group state for controlling the active slide
item	{ props: CarouselDelimiterProps; item: { id: string; value: unknown; disabled: boolean | undefined; }; }	Custom delimiter (navigation dot) for each slide.
next	{ props: ControlProps; }	Button that moves to the next slide. The slot props are ready to bind to your own button
prev	{ props: ControlProps; }	Button that moves to the previous slide. The slot props are ready to bind to your own button

CdsCarouselItem

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.
disabled	boolean | null | undefined	null	Disabled state
draggable	boolean | "true" | "false" | undefined	—	Controls whether the image can be dragged (the draggable attribute).
eager	boolean | undefined	—	Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO.
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.
reverseTransition	string | boolean | undefined	—	Transition used when the slide appears in the reverse direction. A transition component name, or false to turn the animation off
selectedClass	string | undefined	—	CSS class applied in the selected state
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 | undefined	—	Transition used when the slide appears in the forward direction. A transition component name, or false to turn the animation off
value	any	—	Value of the component within the group
width	string | number | undefined	—	Component width

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.