React
Carousel
Tutorial
Accessibility
 · 12 min read

Pure React Carousel: The Only Setup & Customization Guide You’ll Actually Need

The React ecosystem has no shortage of carousel libraries — and yet, somehow, most of them manage to be either
bloated, inaccessible, or stubbornly opinionated about your CSS. Enter
pure-react-carousel:
a lightweight, WAI-ARIA compliant React carousel component that hands you the controls and
gets out of your way. No jQuery. No magic. Just composable React components and a sensible API.

In this guide, you’ll get a full walkthrough — from
pure-react-carousel installation and
setup to navigation, dots, and deep
customization. Whether you’re building a
React image carousel, a product gallery, or a touch-enabled
React slider component, this tutorial has you covered.

Why pure-react-carousel Stands Out Among React Carousel Libraries

Let’s be honest: the bar for React carousel libraries isn’t exactly set in the stratosphere.
Most options either drag in a mountain of dependencies, override your global styles without asking, or treat
accessibility as a stretch goal. pure-react-carousel
takes a deliberately different approach — it’s a collection of primitive components you compose yourself,
which means you’re building your carousel, not fighting someone else’s.

The library ships with zero hard opinions about layout. CarouselProvider, Slider,
Slide, ButtonBack, ButtonNext, and DotGroup are all
independent pieces. You decide how they’re arranged, styled, and extended. This composability is exactly
why teams building complex React image galleries or custom React carousel sliders
tend to reach for it over heavier alternatives like react-slick or Swiper.

Accessibility is baked in, not bolted on. The library follows WAI-ARIA carousel patterns, which means
keyboard navigation, screen reader support, and proper ARIA roles work out of the box. In a world where
carousels are routinely cited as accessibility anti-patterns, that’s not a small thing — it’s the whole point.
If you want a React carousel component that won’t get your site flagged in an accessibility audit,
this is a serious contender.

pure-react-carousel Installation: Getting the Package Into Your Project

Getting started is refreshingly uneventful. You need Node.js, an existing React project (Create React App,
Vite, Next.js — all work), and about forty seconds of your life. Run the following in your project root:

# With npm
npm install pure-react-carousel

# With yarn
yarn add pure-react-carousel

# With pnpm
pnpm add pure-react-carousel

After installation, you’ll need to import the library’s base CSS once — typically in your root
App.jsx or a global stylesheet. This stylesheet handles the core layout mechanics of the slider.
It’s intentionally minimal; it won’t override your design system or inject opinionated color values.

import 'pure-react-carousel/dist/react-carousel.es.css';

That’s the entire pure-react-carousel setup ceremony. No config files, no provider wrappers
at the app root, no peer dependency nightmares. The library supports React 16.3+ and is compatible with
TypeScript projects — type definitions are included in the package via @types/pure-react-carousel
if you’re on an older version, though modern releases bundle them natively.

Building Your First React Image Carousel: Core Structure

The mental model behind pure-react-carousel is straightforward: CarouselProvider
is the state container that knows how many slides you have and how big they are. Everything else —
Slider, Slide, navigation buttons — must live inside it to access that shared state
via React context. Think of it as a self-contained universe for your carousel logic.

Here’s a minimal but fully functional pure-react-carousel example — a three-slide
React image carousel with forward and back navigation:

import React from 'react';
import {
  CarouselProvider,
  Slider,
  Slide,
  ButtonBack,
  ButtonNext,
} from 'pure-react-carousel';
import 'pure-react-carousel/dist/react-carousel.es.css';

const ImageCarousel = () => (
  <CarouselProvider
    naturalSlideWidth={800}
    naturalSlideHeight={500}
    totalSlides={3}
    isIntrinsicHeight={true}
  >
    <Slider>
      <Slide index={0}>
        <img src="/images/slide-1.jpg" alt="Mountain landscape at dawn" />
      </Slide>
      <Slide index={1}>
        <img src="/images/slide-2.jpg" alt="Urban skyline at night" />
      </Slide>
      <Slide index={2}>
        <img src="/images/slide-3.jpg" alt="Coastal cliffs in summer" />
      </Slide>
    </Slider>
    <ButtonBack>← Back</ButtonBack>
    <ButtonNext>Next →</ButtonNext>
  </CarouselProvider>
);

export default ImageCarousel;

A few props deserve attention here. naturalSlideWidth and naturalSlideHeight define
the intrinsic aspect ratio of your slides — not their actual rendered size. The carousel uses these values to
maintain proportional scaling across screen widths. Setting isIntrinsicHeight={true} tells the
slider to size itself based on the actual content height, which is almost always what you want when working with
images of varying dimensions. Without it, you’ll get a fixed aspect-ratio box, which can produce awkward whitespace.

Notice that ButtonBack and ButtonNext are siblings of Slider, not nested
inside it. That’s intentional and important — the library uses React context to connect all child components to
CarouselProvider, so placement within the JSX tree is flexible. You can absolutely put your navigation
buttons above the slider, below it, or in a completely separate section of your layout, as long as they remain
descendants of CarouselProvider.

React Carousel Navigation: Buttons, Dots, and Keyboard Control

A React carousel slider without navigation is just a div with ambitions. The
pure-react-carousel navigation system gives you three primitives:
ButtonBack, ButtonNext, ButtonFirst, ButtonLast,
and the higher-level DotGroup component for paginated dot indicators. Each is a fully
accessible HTML button under the hood — and each renders disabled automatically when it has no valid
target slide, which is genuinely thoughtful UX you’d otherwise implement yourself.

Adding pure-react-carousel dots to your existing carousel takes exactly one import and
one component:

import {
  CarouselProvider,
  Slider,
  Slide,
  ButtonBack,
  ButtonNext,
  DotGroup,
} from 'pure-react-carousel';

// Inside your JSX, after the Slider:
<DotGroup />

DotGroup automatically renders one dot per slide based on the totalSlides count
in CarouselProvider. The active slide’s dot gets an aria-selected="true" attribute,
which screen readers announce correctly. You can customize dot rendering via the renderDots prop
for full control over markup, or style the generated dots by targeting the
.carousel__dot and .carousel__dot--selected CSS classes.

For keyboard navigation, the library handles focus management internally. Users can Tab to the slider region
and navigate slides using arrow keys. If you need to handle custom keyboard events — say, triggering slide
changes from a parent component — the withStore HOC or the useStore hook exposes
the full carousel state and dispatch methods. It’s an escape hatch worth knowing about, though most projects
won’t need it.

pure-react-carousel Customization: Styling, Animation, and Advanced Config

This is where the library’s philosophy really pays off. Because pure-react-carousel customization
is entirely CSS-driven, you’re not fighting inline styles or hunting down !important overrides.
Every component renders with predictable CSS class names, and the base stylesheet is thin enough that you can
override essentially anything without feeling like you’re defusing a bomb.

Want to style your navigation buttons to match your design system? Target .carousel__back-button
and .carousel__next-button. Need a custom slide transition? Override
.carousel__slider-tray--animate with your own transition or
transform declaration. Here’s a practical example that adds custom arrow buttons and a
smooth fade-style overlay effect:

/* carousel-overrides.css */

.carousel__back-button,
.carousel__next-button {
  background: rgba(0, 0, 0, 0.55);
  border: none;
  border-radius: 50%;
  color: #ffffff;
  cursor: pointer;
  font-size: 1.25rem;
  height: 44px;
  width: 44px;
  display: flex;
  align-items: center;
  justify-content: center;
  transition: background 0.2s ease;
}

.carousel__back-button:hover,
.carousel__next-button:hover {
  background: rgba(0, 0, 0, 0.8);
}

.carousel__back-button:disabled,
.carousel__next-button:disabled {
  opacity: 0.3;
  cursor: not-allowed;
}

.carousel__dot {
  background: #ccc;
  border: none;
  border-radius: 50%;
  height: 10px;
  width: 10px;
  margin: 0 4px;
  padding: 0;
  cursor: pointer;
  transition: background 0.2s ease;
}

.carousel__dot--selected {
  background: #4f46e5;
}

Beyond styling, CarouselProvider accepts a rich set of behavioral props. Set
isPlaying={true} with an interval={4000} for autoplay. Use
visibleSlides={2} to show multiple slides simultaneously — great for product grids.
Enable infinite={true} for a looping React carousel slider that wraps
from the last slide back to the first. And if you need drag-to-scroll behavior on desktop as well as
touch, dragEnabled={true} handles both interactions through the same pointer event system.

Building a Responsive React Image Gallery with pure-react-carousel

Responsiveness isn’t a built-in toggle — it’s something you design into your layout. Since
pure-react-carousel uses a ratio-based sizing system, the slider itself scales proportionally
as its container resizes. The real work is in making visibleSlides adapt to screen width, which
the library doesn’t handle natively (a fair tradeoff for keeping the bundle lean). The standard approach is
to combine a window resize hook with conditional prop values.

import { useState, useEffect } from 'react';

const useVisibleSlides = () => {
  const [visibleSlides, setVisibleSlides] = useState(1);

  useEffect(() => {
    const update = () => {
      const width = window.innerWidth;
      if (width >= 1024) setVisibleSlides(3);
      else if (width >= 640) setVisibleSlides(2);
      else setVisibleSlides(1);
    };

    update();
    window.addEventListener('resize', update);
    return () => window.removeEventListener('resize', update);
  }, []);

  return visibleSlides;
};

// Usage:
const MyGallery = () => {
  const visibleSlides = useVisibleSlides();

  return (
    <CarouselProvider
      naturalSlideWidth={400}
      naturalSlideHeight={300}
      totalSlides={9}
      visibleSlides={visibleSlides}
      step={visibleSlides}
      isIntrinsicHeight={true}
    >
      {/* Slider and controls */}
    </CarouselProvider>
  );
};

This pattern gives you a React image gallery that shows one slide on mobile, two on tablet,
and three on desktop — with the step count always matching the visible count so navigation feels clean.
The hook is reusable across multiple carousels on the same page, and because state lives at the component level,
different carousels can have entirely different breakpoint configs without any global coordination.

For Next.js users: be mindful of SSR. Since window isn’t available during server-side rendering,
initialize visibleSlides to your mobile default (usually 1) and let the
useEffect correct it on the client. This prevents hydration mismatches and ensures the carousel
renders a usable layout even before JavaScript kicks in — which also happens to be good for your Core Web Vitals.

pure-react-carousel vs Other React Carousel Libraries: A Realistic Comparison

No library exists in a vacuum. Here’s where pure-react-carousel actually sits in the
landscape, without the usual cheerleading. react-slick (a jQuery Slick port) has a massive
community and tons of prebuilt options, but it’s heavier, has known accessibility gaps, and its CSS overrides
can be a genuine headache. Swiper.js is feature-rich and visually impressive, but at ~120KB
(gzipped), it’s overkill for most standard carousel use cases and introduces a non-React API surface.

Embla Carousel is the closest modern competitor — it’s also lightweight, framework-agnostic,
and accessibility-conscious. The key difference is architectural: Embla exposes a vanilla JS API that you hook
into with React bindings, while pure-react-carousel is a native React component system from the ground up.
If you’re already thinking in React context and hooks, pure-react-carousel tends to feel more natural.
If you need the same carousel code to work across a React app and a plain HTML page, Embla is the better pick.

Where pure-react-carousel genuinely shines is the combination of accessibility-first design,
composable architecture, and a minimal footprint. It’s around 15KB gzipped — a number that tends to matter
when you’re optimizing a page that already carries a React bundle. The tradeoff is that advanced effects
(fade transitions, 3D transforms, complex drag physics) require more custom work than you’d need with Swiper.
Know your requirements before committing: for standard image carousels, product sliders, and galleries,
pure-react-carousel is an excellent default choice.

Common Pitfalls and Pro Tips for pure-react-carousel

A few patterns come up repeatedly when teams adopt this library. First: always provide
alt text for slide images. The library’s ARIA implementation does its part, but
meaningful alternative text on every <img> element is still your responsibility.
An accessible carousel with empty alt attributes is an oxymoron that will still fail an audit.

• Missing CSS import — The most common setup issue. If your slider renders as a vertical list of images instead of a horizontal track, you’ve forgotten import 'pure-react-carousel/dist/react-carousel.es.css'. It happens to everyone once.
• Mismatched totalSlides — If totalSlides doesn’t match the actual number of <Slide> components, navigation breaks in subtle ways. Always keep them in sync, especially when generating slides from dynamic data.
• Autoplay and reduced motion — If you enable isPlaying, respect the prefers-reduced-motion media query. Users who’ve opted out of motion effects should not have auto-advancing carousels forced on them. Check window.matchMedia('(prefers-reduced-motion: reduce)') before enabling autoplay.

For performance, lazy-load images inside slides using native loading="lazy" or a library like
react-intersection-observer. Since slides outside the visible viewport are still rendered in
the DOM (for smooth transition purposes), un-optimized images across ten or more slides will slow your
initial page load noticeably. A loading="lazy" attribute on each slide image costs nothing
and buys you meaningful improvement in Largest Contentful Paint scores.

Finally, if you need to programmatically control the carousel from outside — say, syncing it with a thumbnail
strip or an external counter — reach for the useStore hook. It exposes the full carousel state
tree and a dispatch function. Dispatching { type: 'ADVANCE_BY', payload: 2 }
will jump forward two slides; { type: 'GO_TO_SLIDE', payload: 0 } resets to the first.
It’s a clean, Redux-flavored API that feels right at home in a modern React codebase.

Full pure-react-carousel Example: Production-Ready Component

Here’s a complete, production-ready pure-react-carousel example that incorporates
everything covered in this guide: image slides, accessible navigation buttons, dot indicators,
responsive visible-slide count, and lazy-loaded images. Drop it into any React project after installing
the library and it will work without modification.

import React from 'react';
import {
  CarouselProvider,
  Slider,
  Slide,
  ButtonBack,
  ButtonNext,
  DotGroup,
} from 'pure-react-carousel';
import 'pure-react-carousel/dist/react-carousel.es.css';
import { useVisibleSlides } from './useVisibleSlides'; // hook from earlier

const slides = [
  { id: 1, src: '/images/slide-1.jpg', alt: 'Mountain landscape at dawn' },
  { id: 2, src: '/images/slide-2.jpg', alt: 'Urban skyline at night' },
  { id: 3, src: '/images/slide-3.jpg', alt: 'Coastal cliffs in summer' },
  { id: 4, src: '/images/slide-4.jpg', alt: 'Forest trail in autumn' },
  { id: 5, src: '/images/slide-5.jpg', alt: 'Desert dunes at golden hour' },
  { id: 6, src: '/images/slide-6.jpg', alt: 'Snowy peaks in winter' },
];

const Gallery = () => {
  const visibleSlides = useVisibleSlides();

  return (
    <div className="gallery-wrapper">
      <CarouselProvider
        naturalSlideWidth={800}
        naturalSlideHeight={533}
        totalSlides={slides.length}
        visibleSlides={visibleSlides}
        step={visibleSlides}
        isIntrinsicHeight={true}
        infinite={true}
        dragEnabled={true}
      >
        <div className="carousel-track">
          <ButtonBack className="nav-btn nav-btn--back" aria-label="Previous slide">
            ←
          </ButtonBack>

          <Slider aria-label="Image gallery">
            {slides.map((slide, index) => (
              <Slide key={slide.id} index={index}>
                <img
                  src={slide.src}
                  alt={slide.alt}
                  loading="lazy"
                  style={{ width: '100%', height: 'auto', display: 'block' }}
                />
              </Slide>
            ))}
          </Slider>

          <ButtonNext className="nav-btn nav-btn--next" aria-label="Next slide">
            →
          </ButtonNext>
        </div>

        <DotGroup className="dot-group" aria-label="Slide navigation dots" />
      </CarouselProvider>
    </div>
  );
};

export default Gallery;

This component handles six images across a responsive grid, auto-adjusting from one to three visible slides
based on viewport width. The infinite={true} prop enables seamless looping; dragEnabled
adds pointer-based drag on desktop in addition to touch on mobile. Every interactive element carries a proper
aria-label, and images are lazy-loaded to keep the initial bundle light.

For a deep dive into additional configurations, edge cases, and real-world integration examples — including
how to pair this component with a CMS-powered image feed — check out the original

Getting Started with pure-react-carousel: Building Image Carousels

guide on Dev.to, which covers several advanced patterns not addressed here.

Frequently Asked Questions