Slides you swipe, drag or step through, with momentum, snapping, loop and autoplay.
Example
import {
Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext,
} from "@elements/ui/carousel";
<Carousel label="Featured" opts={{ loop: true }}>
<CarouselContent>
<CarouselItem e:for={item of items}>...</CarouselItem>
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>
<Carousel index={state.slide} autoplay={4000} dots>...</Carousel>
Parts
| Part |
What it is |
Carousel |
The root: a region with aria-roledescription carousel. Owns the engine, the index and the keyboard. |
CarouselContent |
The viewport (clips) and the track the engine moves. class goes on the track. |
CarouselItem |
One slide: a group with aria-roledescription slide, named "N of M" unless label is set. |
CarouselPrevious |
An icon button that scrolls back; disabled at the start unless looping. |
CarouselNext |
An icon button that scrolls forward; disabled at the end unless looping. |
.carousel-rotation |
The rotation control autoplay renders: the first tab stop, its label says what it will do. |
.carousel-dots |
The slide pickers dots renders: one button per snap, the current one aria-disabled. |
Attributes
Carousel
| Attribute |
Type |
Default |
Description |
orientation |
"horizontal" | "vertical" |
"horizontal" |
Scroll axis (engine axis x or y). |
opts |
CarouselOpts |
{} |
Engine options: align, loop, dragFree, slidesToScroll, containScroll, skipSnaps, duration, startIndex, watchDrag, breakpoints and the rest. |
plugins |
CarouselPlugin[] |
[] |
Plugins with init(api) and destroy(). This package ships Autoplay, AutoScroll, AutoHeight, ClassNames, Fade and WheelGestures. |
index |
number (two-way) |
0 |
The selected snap. Bind it to read the current slide or set it to go to one. |
label |
string |
"" |
The region's accessible name. Do not include the word carousel. |
dir |
"ltr" | "rtl" | "" |
"" |
Reading direction; the engine's direction follows it. |
autoplay |
number |
0 |
Milliseconds per slide; 0 is off. Adds the rotation control; hovering pauses, keyboard focus stops. |
dots |
boolean |
false |
Renders a picker button per snap under the slides. |
pickers |
"group" | "tabs" |
"group" |
group: picker buttons, the current one aria-disabled. tabs: a tablist whose tabs control the slides as tabpanels (APG tabbed carousel). |
role |
"region" | "group" |
"region" |
The container's role. Name a group with attrs aria-labelledby when a heading labels it. |
onSelect |
(index: number) => void |
() => {} |
The selected snap changed. |
onApi |
(api: CarouselApi) => void |
() => {} |
The engine's API once ready: scrollTo, scrollSnapList, scrollProgress, on(event). |
CarouselItem
| Attribute |
Type |
Default |
Description |
label |
string |
"" |
The slide's name; default "N of M". |
CarouselPrevious, CarouselNext
| Attribute |
Type |
Default |
Description |
variant |
"primary" | "secondary" | "outline" | "ghost" |
"outline" |
Button look. |
size |
"xs" | "sm" | "md" | "lg" |
"md" |
Button size; the button stays centered just outside the track. |
label |
string |
"Previous slide" / "Next slide" |
The button's accessible name. |
all
| Attribute |
Type |
Default |
Description |
class, attrs |
string, Record |
"", {} |
Extra classes and attributes. On CarouselContent, class goes on the track and attrs on the viewport. |
Slots
| Slot |
Part |
Content |
default |
Carousel |
CarouselContent, then CarouselPrevious and CarouselNext (anywhere inside). |
default |
CarouselContent |
CarouselItem slides. |
default |
CarouselItem |
The slide's content. |
Keyboard
| Keys |
Action |
ArrowLeft / ArrowRight |
Focus inside a horizontal carousel: previous and next slide (mirrored under rtl). |
ArrowUp / ArrowDown |
Focus inside a vertical carousel: previous and next slide. |
Tab / Shift + Tab |
Through the rotation control, the slides' content, the buttons and the pickers, in page order. |
Enter / Space |
On a button: activates it without moving focus, so it can be pressed again. |
ArrowLeft / ArrowRight, Home / End |
On a tab picker (pickers tabs): the previous, next, first or last tab and its slide; wraps. |
Data attributes
| Attribute |
Values |
On |
Description |
data-orientation |
"horizontal" | "vertical" |
root |
|
data-ready |
present |
root |
Once the engine is running. |
data-autoplay |
present |
root |
|
data-in-view |
present |
.carousel-item |
While the slide is in view. |
data-disabled |
present |
CarouselPrevious, CarouselNext |
Nothing more that way. |
data-state |
"active" | "inactive" |
.carousel-dot |
|
data-pickers |
"group" | "tabs" |
.carousel-dots |
|
data-state |
"playing" | "stopped" |
.carousel-rotation |
|
--carousel-item-size |
length |
root or item |
Slide flex-basis; default 100%. |
--carousel-gap |
length |
root |
Space between slides; default --space-4. |
Accessibility
- The root is a region with aria-roledescription="carousel" and label as its name; each slide is a group with aria-roledescription="slide" named "N of M" (WAI-ARIA carousel pattern).
- The track is a polite live region (aria-atomic false) so a screen reader hears the new slide, and off while autoplay rotates.
- Previous, next, picker and rotation buttons keep focus when pressed. The current picker is aria-disabled, not disabled, so it stays reachable.
- pickers tabs follows the APG tabbed carousel: a tablist labelled "Choose slide to display", tabs named for their slides, slides as tabpanels.
- Autoplay: the rotation control is the first tab stop and its label says what it will do; rotation pauses while hovered and stops when keyboard focus enters.
See also