Skip to content

Carousel

A carousel with three modes: slide (full-bleed background slides with an overlay), gallery (a scrolling row of cards), and coverflow — a 3D “jukebox” where the active item is centered and its neighbors recede (set orientation="vertical" to stack the flow top-to-bottom). Render custom slide content with the children snippet ({ item, index, active }).

<script>
import Carousel from "@invisible-ui/svelte/Carousel.svelte";
</script>

In Elements:

<ds-carousel label="Featured photos" loop>
<article>First slide</article>
<article>Second slide</article>
<article>Third slide</article>
</ds-carousel>

Each child becomes a slide. Without children, set the items property to draw the built-in slides. The element sends change with detail.index.

PropTypeDefaultDescription
items *CarouselSlide[]—
variant"slide" | "gallery" | "coverflow""slide"
orientation"horizontal" | "vertical""horizontal"Coverflow only: lay the flow out horizontally (default) or vertically.
loopbooleanfalse
showIndicatorsbooleantrueShow the dot indicators.
label *string—Accessible name for the carousel.
prevLabelstring | undefinedundefinedAccessible labels for the arrows.
nextLabelstring | undefinedundefinedAccessible labels for the arrows.
onIndexChange((index: number) => void) | undefinedundefinedCalled when the active slide changes.
childrenSnippet<[{ item: CarouselSlide; index: number; active: boolean }]> | undefinedundefinedCustom markup for every item. Defaults to the built-in slide.

Each slide’s image is rendered as given: pass only URLs you trust or have sanitized. See Security.

  • Labelled region with previous/next controls and indicator buttons; the active slide is tracked for assistive tech. The role names, the “N of M” slide names and the indicator names come from the message catalog.
  • Coverflow neighbours are scaled and turned, never faded, so their text keeps its contrast; slides more than two places away are hidden.
  • The built-in slide’s title sits on a dark overlay that stays at least 55% black. White text keeps 4.76:1 or better over the lightest image (measured against a white image: 4.76:1 at 55%, 8.52:1 at the 70% base).
  • The slide track, the coverflow and the gallery scroll do not animate under prefers-reduced-motion.
  • In right-to-left text Left and Right swap, so the arrows keep following the reading direction; the page’s dir is read when a key is pressed, with or without a locale provider. The previous and next arrows are mirrored, the slide track moves the other way, and the coverflow places the next slide on the left.
<Carousel label="Photos" items={[{ image: "/a.jpg", title: "A" }]} />

In React, renderItem replaces the children snippet, and index with onIndexChange makes the current slide controlled:

<Carousel
label="Albums"
variant="gallery"
items={albums}
index={current}
onIndexChange={setCurrent}
renderItem={({ item, active }) => <Card title={String(item.title)} surface={active ? "default" : "secondary"} />}
/>

Themeable via --ds-carousel-*.