React Aria Carousel

React Aria Carousel is a collection of React hooks and components that provide the behavior and accessibility implementation for building a carousel. Unlike many other carousels, this implementation uses the latest browser and DOM APIs for scrolling and snapping.

Features

Native browser scroll-snapping and smooth-scrolling for performant transitions across pointer types.
Comprehensive behavior and accessibility coverage for all elements of a carousel, including pagination, infinite scrolling, autoplay, and more.
Support for showing one or many items per page, implemented with responsive-design.
Support for vertical and horizontal scrolling.
Support for infinite scrolling.
Support for autoplay with affordances for disabling it.
Support for mouse dragging.
Written in TypeScript.

Installation

npm install react-aria-carousel

Usage

Anatomy

import {
  Carousel,
  CarouselButton,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
 
<Carousel>
  <CarouselAutoplayControl />
  <CarouselButton dir="prev" />
  <CarouselButton dir="next" />
  <CarouselScroller>
    <CarouselItem />
  </CarouselScroller>
  <CarouselTabs>
    {(page) => (
      <CarouselTab index={page.index} />
    )}
  </CarouselTabs>
</Carousel>

Carousels have a root element denoting the carousel region, which contains all of the different parts of the carousel, including the scrolling container, next and previous buttons, and optionally, tabs and the autoplay toggle.

Below is a simple example with minimal styles to show all of the different parts working together.

App.tsx

./styles.css

import { StockPhoto } from "@/components/Image";
import {
  Carousel,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
 
import styles from "./styles.module.css";
 
export function Basic() {
  return (
    <Carousel className={styles.root} spaceBetweenItems="16px">
      <div className={styles.buttons}>
        <CarouselButton dir="prev" className={styles.button}>
          Previous
        </CarouselButton>
        <CarouselButton dir="next" className={styles.button}>
          Next
        </CarouselButton>
      </div>
      <CarouselScroller className={styles.scroller}>
        <Item index={0} />
        <Item index={1} />
        <Item index={2} />
        <Item index={3} />
      </CarouselScroller>
      <CarouselTabs className={styles.tabs}>
        {(item) => (
          <CarouselTab className={styles.tab} index={item.index}>
            {item.index + 1}
          </CarouselTab>
        )}
      </CarouselTabs>
    </Carousel>
  );
}
 
function Item({ index }: { index: number }) {
  return (
    <CarouselItem className={styles.item}>
      <StockPhoto index={index} />
    </CarouselItem>
  );
}

Multiple Items

The number of items present on a page can be changed with the itemsPerPage prop. You can change the spacing between items with the spaceBetweenItems prop.

App.tsx

./styles.module.css

import {
  Carousel,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
import { FaChevronLeft, FaChevronRight } from "react-icons/fa6";
 
import styles from "./styles.module.css";
 
export function MultipleItems() {
  return (
    <Carousel
      aria-label="Featured Collection"
      className={styles.root}
      itemsPerPage={2}
      spaceBetweenItems="12px"
    >
      <CarouselButton className={styles.button} data-dir="prev" dir="prev">
        <FaChevronLeft />
      </CarouselButton>
      <CarouselScroller className={styles.scroller}>
        <Item index={0} />
        <Item index={1} />
        <Item index={2} />
        <Item index={3} />
        <Item index={4} />
        <Item index={5} />
      </CarouselScroller>
      <CarouselButton className={styles.button} dir="next" data-dir="next">
        <FaChevronRight />
      </CarouselButton>
      <CarouselTabs className={styles.tabs}>
        {(page) => <CarouselTab index={page.index} className={styles.tab} />}
      </CarouselTabs>
    </Carousel>
  );
}
 
const colors = [
  "sky",
  "red",
  "green",
  "blue",
  "orange",
  "violet",
  "lime",
  "fuchsia",
  "purple",
  "pink",
  "rose",
];
 
function Item({ index }: { index: number }) {
  return (
    <CarouselItem
      className={styles.item}
      style={{
        backgroundColor: `var(--colors-${colors[index]}-6)`,
      }}
    >
      {index + 1}
    </CarouselItem>
  );
}

Looping

By default, the carousel will not loop if one scrolls to either end. You can force the carousel to "wrap" in two different ways.

If the loop prop is set to "infinite", the carousel will give the appearance of seamlessly wrapping to the opposite end.

If the loop props is set to "native", the user still won't be able to scroll to the other end. However, the next and previous buttons and keyboard controls will scroll the user to the other end. ("Native" in this case means that the behavior of the scroll container aren't manipulated, it just provides the functionality to scroll the user to the other end.)

Infinite loopingNative looping

App.tsx

./styles.module.css

import { ChangeEvent, useState } from "react";
import {
  Carousel,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
import { FaChevronLeft, FaChevronRight } from "react-icons/fa6";
 
import styles from "./styles.module.css";
 
export function Looping() {
  const [loop, setLoop] = useState<"infinite" | "native">("infinite");
 
  function handleChange(e: ChangeEvent) {
    setLoop((e.target as HTMLInputElement).value as "infinite" | "native");
  }
 
  return (
    <>
      <div style={{ display: "flex", gap: "16px", marginBottom: "16px" }}>
        <label>
          <input
            type="radio"
            value="infinite"
            onChange={handleChange}
            checked={loop === "infinite"}
          />
          Infinite looping
        </label>
        <label>
          <input
            type="radio"
            value="native"
            onChange={handleChange}
            checked={loop === "native"}
          />
          Native looping
        </label>
      </div>
      <Carousel
        aria-label="Featured Collection"
        className={styles.root}
        spaceBetweenItems="12px"
        loop={loop}
      >
        <CarouselButton className={styles.button} data-dir="prev" dir="prev">
          <FaChevronLeft />
        </CarouselButton>
        <CarouselScroller className={styles.scroller}>
          <Item index={0} />
          <Item index={1} />
          <Item index={2} />
          <Item index={3} />
          <Item index={4} />
          <Item index={5} />
          <Item index={6} />
        </CarouselScroller>
        <CarouselButton className={styles.button} dir="next" data-dir="next">
          <FaChevronRight />
        </CarouselButton>
        <CarouselTabs className={styles.tabs}>
          {(page) => <CarouselTab index={page.index} className={styles.tab} />}
        </CarouselTabs>
      </Carousel>
    </>
  );
}
 
const colors = [
  "sky",
  "red",
  "green",
  "blue",
  "orange",
  "violet",
  "lime",
  "fuchsia",
  "purple",
  "pink",
  "rose",
];
 
function Item({ index }: { index: number }) {
  return (
    <CarouselItem
      className={styles.item}
      style={{
        backgroundColor: `var(--colors-${colors[index]}-6)`,
      }}
    >
      {index + 1}
    </CarouselItem>
  );
}

Orientation

By default, the carousel will scroll horizontally. This can be changed to scroll vertically with the orientation prop.

App.tsx

./styles.module.css

import {
  Carousel,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
import { FaChevronLeft, FaChevronRight } from "react-icons/fa6";
 
import styles from "./styles.module.css";
 
export function Orientation() {
  return (
    <Carousel
      aria-label="Featured Collection"
      className={styles.root}
      spaceBetweenItems="12px"
      orientation="vertical"
    >
      <CarouselButton className={styles.button} data-dir="prev" dir="prev">
        <FaChevronLeft />
      </CarouselButton>
      <CarouselScroller className={styles.scroller}>
        <Item index={0} />
        <Item index={1} />
        <Item index={2} />
        <Item index={3} />
        <Item index={4} />
        <Item index={5} />
        <Item index={6} />
      </CarouselScroller>
      <CarouselButton className={styles.button} dir="next" data-dir="next">
        <FaChevronRight />
      </CarouselButton>
      <CarouselTabs className={styles.tabs}>
        {(page) => <CarouselTab index={page.index} className={styles.tab} />}
      </CarouselTabs>
    </Carousel>
  );
}
 
const colors = [
  "sky",
  "red",
  "green",
  "blue",
  "orange",
  "violet",
  "lime",
  "fuchsia",
  "purple",
  "pink",
  "rose",
];
 
function Item({ index }: { index: number }) {
  return (
    <CarouselItem
      className={styles.item}
      style={{
        backgroundColor: `var(--colors-${colors[index]}-6)`,
      }}
    >
      {index + 1}
    </CarouselItem>
  );
}

Mouse Dragging

The carousel uses CSS scroll snap to position slides at various snap positions. This allows users to scroll through the slides very naturally, especially on touch devices. Unfortunately, desktop users won’t be able to click and drag with a mouse, which can feel unnatural. The carousel provides this functionality with the mouseDragging prop.

This example is best demonstrated using a mouse. Try clicking and dragging the slide to move it.

App.tsx

./styles.module.css

import {
  Carousel,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
import { FaChevronLeft, FaChevronRight } from "react-icons/fa6";
 
import styles from "./styles.module.css";
 
export function MouseDragging() {
  return (
    <Carousel
      aria-label="Featured Collection"
      className={styles.root}
      spaceBetweenItems="12px"
      mouseDragging
    >
      <CarouselButton className={styles.button} data-dir="prev" dir="prev">
        <FaChevronLeft />
      </CarouselButton>
      <CarouselScroller className={styles.scroller}>
        <Item index={0} />
        <Item index={1} />
        <Item index={2} />
        <Item index={3} />
        <Item index={4} />
        <Item index={5} />
        <Item index={6} />
      </CarouselScroller>
      <CarouselButton className={styles.button} dir="next" data-dir="next">
        <FaChevronRight />
      </CarouselButton>
      <CarouselTabs className={styles.tabs}>
        {(page) => <CarouselTab index={page.index} className={styles.tab} />}
      </CarouselTabs>
    </Carousel>
  );
}
 
const colors = [
  "sky",
  "red",
  "green",
  "blue",
  "orange",
  "violet",
  "lime",
  "fuchsia",
  "purple",
  "pink",
  "rose",
];
 
function Item({ index }: { index: number }) {
  return (
    <CarouselItem
      className={styles.item}
      style={{
        backgroundColor: `var(--colors-${colors[index]}-6)`,
      }}
    >
      {index + 1}
    </CarouselItem>
  );
}

Autoplay

Use the autoplay prop to automatically progress the carousel, dictated by the autoplayInterval prop. This functionality works great with the loop prop enabled. For best usability and accessibility, autoplay will pause if the user starts interacting with the carousel, and will resume when the stop interacting with it. Autoplay will also be disabled if the user's operating system or browser settings has the "prefers reduced motion" option enabled.

It's very important to include the CarouselAutoplayControl component when using this prop! Users must be able to disable this functionality.

App.tsx

./styles.module.css

import {
  Carousel,
  CarouselAutoplayControl,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
import { FaChevronLeft, FaChevronRight } from "react-icons/fa6";
 
import styles from "./styles.module.css";
 
export function Autoplay() {
  return (
    <Carousel
      aria-label="Featured Collection"
      className={styles.root}
      spaceBetweenItems="12px"
      loop="infinite"
      autoplay
      autoplayInterval={5000}
    >
      <CarouselAutoplayControl className={styles.autoplay}>
        {({ autoplayUserPreference }) =>
          autoplayUserPreference ? "Disable autoplay" : "Enable autoplay"
        }
      </CarouselAutoplayControl>
      <CarouselButton className={styles.button} data-dir="prev" dir="prev">
        <FaChevronLeft />
      </CarouselButton>
      <CarouselScroller className={styles.scroller}>
        <Item index={0} />
        <Item index={1} />
        <Item index={2} />
        <Item index={3} />
        <Item index={4} />
        <Item index={5} />
        <Item index={6} />
      </CarouselScroller>
      <CarouselButton className={styles.button} dir="next" data-dir="next">
        <FaChevronRight />
      </CarouselButton>
      <CarouselTabs className={styles.tabs}>
        {(page) => <CarouselTab index={page.index} className={styles.tab} />}
      </CarouselTabs>
    </Carousel>
  );
}
 
const colors = [
  "sky",
  "red",
  "green",
  "blue",
  "orange",
  "violet",
  "lime",
  "fuchsia",
  "purple",
  "pink",
  "rose",
];
 
function Item({ index }: { index: number }) {
  return (
    <CarouselItem
      className={styles.item}
      style={{
        backgroundColor: `var(--colors-${colors[index]}-6)`,
      }}
    >
      {index + 1}
    </CarouselItem>
  );
}

Scroll Hints

The carousel has two different ways to hint to users that there are more items in the carousel.

The scrollPadding prop simply applies CSS scroll-padding to the scroll container. This has the effect of hinting the presence of items on either side of the carousel.

You can also manipulate the itemsPerPage prop to hint at more items. If you use a non-integer number, like 2.25, the carousel will show a quarter of the following item in the list. This option has the benefit of keeping the edges of the carousel nicely aligned to its container (as opposed to scrollPadding).

Scroll Padding

Fractional Items per Page

App.tsx

./styles.module.css

import {
  Carousel,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
import { FaChevronLeft, FaChevronRight } from "react-icons/fa6";
 
import styles from "./styles.module.css";
 
export function ScrollHints() {
  return (
    <div
      style={{
        display: "flex",
        gap: "16px",
        flexDirection: "column",
      }}
    >
      <div style={{ "--aspect-ratio": "16 / 9" }}>
        <h4 style={{ marginTop: 0 }}>Scroll Padding</h4>
        <ComposedCarousel scrollPadding="15%" />
      </div>
      <div style={{ "--aspect-ratio": "4 / 3" }}>
        <h4>Fractional Items per Page</h4>
        <ComposedCarousel itemsPerPage={2.25} />
      </div>
    </div>
  );
}
 
function ComposedCarousel(props) {
  return (
    <Carousel
      {...props}
      aria-label="Featured Collection"
      className={styles.root}
      spaceBetweenItems="12px"
    >
      <CarouselButton className={styles.button} data-dir="prev" dir="prev">
        <FaChevronLeft />
      </CarouselButton>
      <CarouselScroller className={styles.scroller}>
        <Item index={0} />
        <Item index={1} />
        <Item index={2} />
        <Item index={3} />
        <Item index={4} />
        <Item index={5} />
        <Item index={6} />
      </CarouselScroller>
      <CarouselButton className={styles.button} dir="next" data-dir="next">
        <FaChevronRight />
      </CarouselButton>
      <CarouselTabs className={styles.tabs}>
        {(page) => <CarouselTab index={page.index} className={styles.tab} />}
      </CarouselTabs>
    </Carousel>
  );
}
 
const colors = [
  "sky",
  "red",
  "green",
  "blue",
  "orange",
  "violet",
  "lime",
  "fuchsia",
  "purple",
  "pink",
  "rose",
];
 
function Item({ index }: { index: number }) {
  return (
    <CarouselItem
      className={styles.item}
      style={{
        backgroundColor: `var(--colors-${colors[index]}-6)`,
        aspectRatio: "var(--aspect-ratio)",
      }}
    >
      {index + 1}
    </CarouselItem>
  );
}

Accessibility & Labeling

React Aria Carousel includes most required labels and HTML semantics by default, but requires a label (via aria-label or aria-labelledby) for the Carousel component for it to properly be described by screen readers.

All other aria attributes and descriptions are provided in English. For non-English languages, they can be overridden. Here's an example of the component translated to Italian:

App.tsx

./styles.module.css

import {
  Carousel,
  CarouselButton,
  CarouselItem,
  CarouselScroller,
  CarouselTab,
  CarouselTabs,
} from "react-aria-carousel";
import { FaChevronLeft, FaChevronRight } from "react-icons/fa6";
 
import styles from "./styles.module.css";
 
export function Translated() {
  return (
    <Carousel
      aria-label="Collezione in primo piano"
      className={styles.root}
      spaceBetweenItems="12px"
      mouseDragging
    >
      <CarouselButton
        className={styles.button}
        data-dir="prev"
        dir="prev"
        aria-label="Pagina precedente"
      >
        <FaChevronLeft />
      </CarouselButton>
      <CarouselScroller
        aria-label="Scorrimento elementi"
        className={styles.scroller}
      >
        <Item label="1 di 3" index={0} />
        <Item label="2 di 3" index={1} />
        <Item label="3 di 3" index={2} />
      </CarouselScroller>
      <CarouselButton
        className={styles.button}
        dir="next"
        data-dir="next"
        aria-label="pagina successiva"
      >
        <FaChevronRight />
      </CarouselButton>
      <CarouselTabs
        className={styles.tabs}
        aria-label="navigazione a carosello"
      >
        {(page) => (
          <CarouselTab
            index={page.index}
            className={styles.tab}
            aria-label={`Vai alla voce ${page.index + 1} di 7`}
          />
        )}
      </CarouselTabs>
    </Carousel>
  );
}
 
const colors = [
  "sky",
  "red",
  "green",
  "blue",
  "orange",
  "violet",
  "lime",
  "fuchsia",
  "purple",
  "pink",
  "rose",
];
 
function Item({ index, label }: { index: number; label: string }) {
  return (
    <CarouselItem
      aria-label={label}
      className={styles.item}
      style={{
        backgroundColor: `var(--colors-${colors[index]}-6)`,
      }}
    >
      {index + 1}
    </CarouselItem>
  );
}

Note: translations may be innaccurate, I used Google Translate for them :).

Hooks

If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API.

import {
  useCarousel,
  useCarouselItem,
  useCarouselTab,
} from "react-aria-carousel";
 
export function Carousel() {
  const [assignScrollerRef, carousel] = useCarousel({
    spaceBetweenItems: "16px",
    itemsPerPage: 2,
  });
 
  const {
    rootProps,
    prevButtonProps,
    nextButtonProps,
    scrollerProps,
    tabProps,
    pages,
    autoplayControlProps,
  } = carousel;
 
  return (
    <div {...rootProps}>
      <button {...autoplayControlProps}>Toggle autoplay</button>
      <div>
        <button {...prevButtonProps}>Previous</button>
        <button {...nextButtonProps}>Next</button>
      </div>
      <div {...scrollerProps} ref={assignScrollerRef}>
        <CarouselItem index={0} state={carousel} />
      </div>
      <div {...tabProps}>
        {pages.map((_, i) => (
          <CarouselTab key={i} index={i} state={carousel} />
        ))}
      </div>
    </div>
  );
}
 
function CarouselItem({ index, state }) {
  const { itemProps } = useCarouselItem({ index }, state);
  return <div {...itemProps} />;
}
 
function CarouselTab({ index, state }) {
  const { tabProps } = useCarouselTab({ index }, state);
  return <div {...tabProps} />;
}