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 }).
Import
Section titled “Import”<script> import Carousel from "@invisible-ui/svelte/Carousel.svelte";</script><script setup> import { Carousel } from "@invisible-ui/vue";</script>import { Carousel } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-carousel></ds-carousel>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.
| Prop | Type | Default | Description |
|---|---|---|---|
items * | CarouselSlide[] | — | |
variant | "slide" | "gallery" | "coverflow" | "slide" | |
orientation | "horizontal" | "vertical" | "horizontal" | Coverflow only: lay the flow out horizontally (default) or vertically. |
loop | boolean | false | |
showIndicators | boolean | true | Show the dot indicators. |
label * | string | — | Accessible name for the carousel. |
prevLabel | string | undefined | undefined | Accessible labels for the arrows. |
nextLabel | string | undefined | undefined | Accessible labels for the arrows. |
onIndexChange | ((index: number) => void) | undefined | undefined | Called when the active slide changes. |
children | Snippet<[{ item: CarouselSlide; index: number; active: boolean }]> | undefined | undefined | Custom markup for every item. Defaults to the built-in slide. |
| Prop | Type | Default | Description |
|---|---|---|---|
items * | CarouselSlide[] | — | |
variant | CarouselVariant | "slide" | |
orientation | CarouselOrientation | "horizontal" | Coverflow only: lay the flow out horizontally (default) or vertically. |
loop | boolean | false | |
showIndicators | boolean | true | Show the slide-picker dots. Defaults to true. |
label * | string | — | Accessible name for the carousel (announced by screen readers). |
prevLabel | string | undefined | Previous button accessible name. Defaults to the catalog's "Previous slide". |
nextLabel | string | undefined | Next button accessible name. Defaults to the catalog's "Next slide". |
index | number | 0 | Current slide index; bindable with v-model:index. |
onIndexChange | (index: number) => void | undefined | Called whenever the current slide changes. |
| Event | Payload |
|---|---|
update:index | index: number |
Slots: default.
| Prop | Type | Default | Description |
|---|---|---|---|
items * | CarouselSlide[] | — | |
variant | CarouselVariant | "slide" | |
orientation | CarouselOrientation | "horizontal" | Coverflow only: lay the flow out horizontally (default) or vertically. |
loop | boolean | false | |
showIndicators | boolean | true | Show the slide-picker dots. Defaults to true. |
label * | string | — | Accessible name for the carousel (announced by screen readers). |
prevLabel | string | — | Previous button accessible name. Defaults to the catalog's "Previous slide". |
nextLabel | string | — | Next button accessible name. Defaults to the catalog's "Next slide". |
index | number | — | Initial or current slide index (controllable mirror). Defaults to 0. |
onIndexChange | (index: number) => void | — | Called whenever the user moves to another slide. |
renderItem | (context: CarouselItemContext) => ReactNode | — | Custom markup for every item. Defaults to the built-in slide. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | the carousel's accessible name, required |
variant | yes | slide|gallery|coverflow; "slide" by default |
orientation | yes | horizontal|vertical; "horizontal" by default |
loop | yes | the ends wrap around |
show-indicators | yes | show-indicators="false" hides the dots |
index | yes | the current slide, from 0 |
prev-label | yes | the previous button's name; "Previous slide" by default |
next-label | yes | the next button's name; "Next slide" by default |
Reactive attributes re-render the element when they change after the first render.
Properties: items (built-in slides), index.
Emits: bubbling change CustomEvent with detail.index after a user action changes the slide.
Each slide’s image is rendered as given: pass only URLs you trust or have
sanitized. See Security.
Accessibility
Section titled “Accessibility”- 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
diris 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.
Example
Section titled “Example”<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-*.