Carousel – Once UI

An interactive component for displaying a collection of images with smooth transitions and navigation controls. The Carousel supports both line and thumbnail indicators for navigation between images.

Five components scroll a row

Pick by the job. Carousel shows one image or slide at a time, with line or thumbnail indicators and autoplay. Swiper is a touch-first gallery on native scroll snapping. ScrollContainer moves a run of cards or tiles, with drag, wrap-around, markers and proximity scaling. Scroller scrolls overflowing chips, tabs or cards behind arrow buttons and edge fades. AutoScroll is a marquee that moves on its own. 3.0 plans to consolidate them.

Carousel

<Carousel
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
  ]}
/>

Indicator

The Carousel supports two types of indicators for navigation: line (default) and thumbnail.

Indicator

<Carousel
  indicator="line"
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
  ]}
/>

<Carousel
  indicator="thumbnail"
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
  ]}
/>

Controls

You can hide the controls with the controls prop.

Controls

<Carousel
  controls={false}
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
  ]}
/>

Aspect ratio

You can customize the aspect ratio of the carousel to fit your design needs.

Aspect ratio

<Carousel
  aspectRatio="4 / 3"
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
  ]}
/>

Auto Play

You can enable auto play with the play prop. Each field has its own default: play={{ auto: true }} moves every 3000ms with a pause button. Autoplay holds while the pointer is over the carousel, stops when keyboard focus comes into it, and does not start for a visitor who asks for reduced motion; the button then offers Play. Name the button in another language with pauseLabel and playLabel, and the carousel itself with aria-label.

Auto Play

<Carousel
  controls={false}
  indicator={false}
  aria-label="Theme previews"
  play={{auto: true, interval: 5000, controls: true, progress: true}}
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
  ]}
/>

Custom content

You can place custom content inside the slides as ReactNode.

Custom content

Slide 1

<Carousel
  items={[
    { slide: <Row height={20} fill center radius="s" background="brand-strong"><Text>Slide 1</Text></Row> },
    { slide: <Row height={20} fill center radius="s" background="accent-strong"><Text>Slide 2</Text></Row> },
  ]}
/>

API reference

	Type	Default
itemsrequired	CarouselItem[]	[]
controls	boolean	true
priority Eager-load the first slide. Use it when the carousel is above the fold.	boolean	false
stretch Drop the intrinsic aspect ratio and let slides fill their box.	boolean	false
indicator	linethumbnailfalse	line
translateY	SpacingTokennumber	—
aspectRatio	string	original
sizes	stringnumber	—
unoptimized	boolean	false
revealedByDefault	boolean	false
thumbnail Sizing of the thumbnail strip when indicator is "thumbnail".	ThumbnailItem	{ scaling: 1, height: "80", sizes: "120px" }
play Autoplay: `auto`, `interval` (3000), `controls` (the pause button, on unless false), `progress`, and the button's `pauseLabel` and `playLabel`.	{ auto?: boolean; interval?: number; controls?: boolean; progress?: boolean; pauseLabel?: string; playLabel?: string; }	{ auto: false, interval: 3000, controls: true }
…and every FlexProps prop	inherited	—
auto	boolean	false