Carousel for React Aria

Previous and next buttons move through a row of slides, one filling the frame.

Use it for a gallery, a few quotes, or a short onboarding sequence. For named panels people jump between, use Tabs. In React, React Aria keeps previous and next labeled, so an icon with no name is not enough.

Installation

Anatomy

Carousel
├── CarouselItem
│   └── CarouselContent
├── CarouselControl
├── CarouselNext
├── CarouselPrevious
├── CarouselIndicator
│   └── CarouselIndicatorGroup
├── CarouselAutoplayTrigger
└── CarouselProgressText

Usage

import { Card, CardContent } from "@/components/ui/card";
import {
  Carousel, CarouselContent, CarouselItem, CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel";

const slides = [1, 2, 3, 4, 5];

const CarouselDemo = () => (
  <Carousel className="w-full max-w-[12rem] sm:max-w-xs">
    <CarouselContent>
      {slides.map((slide) => (
        <CarouselItem key={slide}>
          <div className="p-1">
            <Card>
              <CardContent className="flex aspect-square items-center justify-center p-6">
                <span className="font-semibold text-4xl">{slide}</span>
              </CardContent>
            </Card>
          </div>
        </CarouselItem>
      ))}
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
  </Carousel>
);

Accessibility

Demos

Size

Each card is narrower than the frame, so two sit side by side and a third can appear once the carousel is wide. Use that for thumbnails or logos, where one full-bleed slide wastes the row. The next card peeks in, which is the hint that more exist. Cap the width or the cards grow until that peek disappears.

Spacing

A multi-card row with a small gap, so neighboring borders do not touch. Tight spacing reads as one group, and a wide gutter reads as separate sections, which fights a carousel. A few pixels is enough when the cards already have an edge. Drop the gap for full-bleed photos that should meet.

Orientation

The track runs downward, about two cards in a fixed height, and the buttons point up and down. Set orientation to vertical and give the content a height, or the column grows with every slide and nothing actually scrolls. A short rail beside a detail view is the fit. A gallery across a page should stay horizontal, which is the default and the direction people expect to swipe.

Api

A line under the carousel says which slide is current, out of five, and updates as you move. The label is your markup, not a built-in caption, so it can match the way the rest of the page speaks. Use it when dots are not enough and a heading or side panel must stay in step. The FAQ shows how each stack reports that index.

Plugin

Slides advance on a two second timer and pause while the pointer is over the track. Leaving the track starts them again. Use a timer for a decorative gallery, not for a sentence someone must read. Keep previous and next, because autoplay is easy to miss, and pausing on hover is the minimum rather than a flourish.

Multiple

On a wide screen several cards share the row, and previous and next hide on small screens where one card already fills the width. Use several per view for tiles people compare, not for a hero. Hiding the buttons works only when a peek of the next card is hint enough. On touch, visible controls beat hoping for a swipe.

Rtl

The numerals are Arabic, and dir is rtl on the carousel, so forward sits where forward is on that page. Previous and next trade sides with the reading order. Set direction on the carousel itself. An ancestor with the right direction can still leave the scroll axis left to right, so try a translated slide rather than English cards with a direction attribute.

FAQ

API Reference