llms.txt

Carousel

Горизонтальная прокрутка слайдов. Принимает children как массив React-элементов и управляет переключением через стрелки, пагинацию и свайп. Поддерживает infiniteScroll, autoSwipe, несколько элементов в viewport (showItems) и управляемый режим (state).

Когда использовать

  • Галереи изображений и медиа.
  • Онбординг с несколькими шагами.
  • Секции «Похожие товары», «Недавние проекты» — несколько карточек в viewport (showItems > 1).

Когда не нужен: для табличных данных (используйте @cloud-ru/ds-tabs), для форм (обычная вертикальная прокрутка), для длинных списков (виртуализация).

Анатомия

Controls visibility

Режим отображения стрелок и пагинации: hover — элементы управления проявляются по наведению (чище в галереях), always — видны всегда (рекомендуется для touch и для onboarding).

Установка

pnpm add @cloud-ru/ds-carousel
import { Carousel } from '@cloud-ru/ds-carousel'

Примеры использования

1. Базовая карусель

1. Базовая карусель
Slide 1
Slide 2
tsx
import { Carousel } from '@cloud-ru/ds-carousel';

export function Basic() {
  return (
    <div style={{ width: 480 }}>
      <Carousel>
        <div style={{ height: 180, background: '#4f46e5', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 1
        </div>
        <div style={{ height: 180, background: '#0ea5e9', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 2
        </div>
      </Carousel>
    </div>
  );
}

2. Три элемента в viewport

2. Три элемента в viewportshowItems=3, кастомный gap
Card 1
Card 2
Card 3
Card 4
Card 5
Card 6
tsx
import { Carousel } from '@cloud-ru/ds-carousel';

export function ThreePerView() {
  return (
    <div style={{ width: 600 }}>
      <Carousel showItems={3} gap='12px'>
        {Array.from({ length: 6 }).map((_, i) => (
          <div
            key={i}
            style={{ height: 120, background: '#f3f4f6', display: 'grid', placeItems: 'center', borderRadius: 8 }}
          >
            Card {i + 1}
          </div>
        ))}
      </Carousel>
    </div>
  );
}

3. Бесконечная с автопрокруткой

3. Бесконечная с автопрокруткойinfiniteScroll + autoSwipe=3 секунды на слайд
Slide 1
Slide 2
Slide 3
tsx
import { Carousel } from '@cloud-ru/ds-carousel';

export function Infinite() {
  return (
    <div style={{ width: 480 }}>
      <Carousel infiniteScroll autoSwipe={3}>
        <div style={{ height: 180, background: '#10b981', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 1
        </div>
        <div style={{ height: 180, background: '#f59e0b', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 2
        </div>
        <div style={{ height: 180, background: '#ec4899', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 3
        </div>
      </Carousel>
    </div>
  );
}

Props

Types

PropsCarouselProps
PropTypeDefaultRequiredDescription
arrowsbooleantruenoИспользовать стрелки для переключения страниц. На mobile по умолчанию скрыты (`CAROUSEL_LAYOUT_PRESETS`), вернуть — через `layoutPresets`.
autoSwipenumber—noАвтоматическое переключение слайдов в секундах
childrenReactElement<any, string | JSXElementConstructor<any>>[]—yesМассив айтемов
classNamestring—noCSS - класснейм
controlsVisibility"always" | "hover"hovernoУправление видимостью стрелок: 'hover' — по ховеру, 'always' — всегда
data-test-idstring—no
gapstringvar(--dimension-2m)noРасстояние между айтемами
infiniteScrollbooleanfalsenoЦикличная прокрутка
layoutPresetsPartial<Record<LayoutType, Partial<CarouselLayoutDefaults>>>—noOverride mobile-дефолтов адаптива для этого инстанса (deep-merge поверх `CAROUSEL_LAYOUT_PRESETS`). Escape-hatch: обычно не нужен — DS-пресет применяется автоматически по `AdaptiveProvider`.
paginationbooleantruenoИспользовать пагинацию для переключения страниц
scrollBynumberMath.trunc(show)noСдвиг айтемов при смене 1 страницы
showItemsnumber1noКол-во отображаемых единовременно айтемов
state{ page: number; onChange(page: number): void; }—noУправление состоянием извне
swipebooleantruenoПереключение страниц свайпом
swipeActivateLengthnumber48noМинимальная длина в px для активации свайпа
transitionnumber0.4noВремя переключения 1 страницы (в s)

CarouselLayoutDefaultsinterface

PropTypeDefaultRequiredDescription
arrowsboolean | undefined—noИспользовать стрелки для переключения страниц. На mobile по умолчанию скрыты (`CAROUSEL_LAYOUT_PRESETS`), вернуть — через `layoutPresets`.

Unions

ControlsVisibilityunion

"always" | "hover"

Related props

LayoutPresetsinterface

PropTypeDefaultRequiredDescription
desktopany—no
desktopSmallany—no
mobileany—no
tabletany—no

Адаптивность

Carousel — адаптивный компонент класса preset-defaults: DOM один, по раскладке меняются только дефолты пропсов. Раскладку компонент читает из контекста @cloud-ru/ds-adaptive — отдельного пропа layoutType нет.

На mobile стрелки скрыты: страницы листаются свайпом и пагинацией.

Пропdesktopmobile
arrowstruefalse

Источник mobile-дефолтов — экспортируемая константа CAROUSEL_LAYOUT_PRESETS.

Как переопределить

Приоритет (от высшего к низшему): layoutPresets[layout] (инстанс) → DS-пресет CAROUSEL_LAYOUT_PRESETS → явный проп (= desktop-значение) → базовый дефолт.

import { Carousel } from '@cloud-ru/ds-carousel'

// Явный проп задаёт desktop-значение, на mobile стрелки по-прежнему скрыты
<Carousel arrows={false}>{items}</Carousel>

// Вернуть стрелки на mobile
<Carousel layoutPresets={{ mobile: { arrows: true } }}>{items}</Carousel>

Storybook

Открыть в Storybook →

Figma

Открыть в Figma →