DEV Community

Joseph Nelson
Joseph Nelson

Posted on

Getting Started with Pure React Carousel: Building Image Carousels

#react #webdev #tutorial #beginners

Pure React Carousel is a lightweight, flexible carousel component library for React applications. It provides a simple API for creating image carousels, content sliders, and navigation components with minimal configuration. This guide walks through setting up and creating carousels using Pure React Carousel with React, from installation to a working implementation. This is part 58 of a series on using Pure React Carousel with React.

Prerequisites

Before you begin, make sure you have:

  • Node.js version 14.0 or higher installed
  • npm, yarn, or pnpm package manager
  • A React project (version 16.8 or higher) or create-react-app setup
  • Basic knowledge of React components
  • Familiarity with JavaScript/TypeScript

Installation

Install Pure React Carousel using your preferred package manager:

npm install pure-react-carousel
Enter fullscreen mode Exit fullscreen mode

Or with yarn:

yarn add pure-react-carousel
Enter fullscreen mode Exit fullscreen mode

Or with pnpm:

pnpm add pure-react-carousel
Enter fullscreen mode Exit fullscreen mode

After installation, your package.json should include:

{
  "dependencies": {
    "pure-react-carousel": "^1.29.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Project Setup

Pure React Carousel requires minimal setup. Import the components and you're ready to use them.

First Example / Basic Usage

Let's create a simple image carousel. Create a new file src/CarouselExample.jsx:

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

function CarouselExample() {
  const images = [
    'https://via.placeholder.com/800x400/007bff/ffffff?text=Slide+1',
    'https://via.placeholder.com/800x400/28a745/ffffff?text=Slide+2',
    'https://via.placeholder.com/800x400/ffc107/000000?text=Slide+3',
    'https://via.placeholder.com/800x400/dc3545/ffffff?text=Slide+4'
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '800px', margin: '0 auto' }}>
      <h2>Basic Carousel Example</h2>
      <CarouselProvider
        naturalSlideWidth={100}
        naturalSlideHeight={50}
        totalSlides={images.length}
      >
        <Slider>
          {images.map((image, index) => (
            <Slide key={index} index={index}>
              <img
                src={image}
                alt={`Slide ${index + 1}`}
                style={{ width: '100%', height: '100%', objectFit: 'cover' }}
              />
            </Slide>
          ))}
        </Slider>
        <ButtonBack style={{
          position: 'absolute',
          left: '10px',
          top: '50%',
          transform: 'translateY(-50%)',
          padding: '10px 15px',
          backgroundColor: 'rgba(0,0,0,0.5)',
          color: 'white',
          border: 'none',
          borderRadius: '4px',
          cursor: 'pointer',
          zIndex: 1
        }}>
          ‹
        </ButtonBack>
        <ButtonNext style={{
          position: 'absolute',
          right: '10px',
          top: '50%',
          transform: 'translateY(-50%)',
          padding: '10px 15px',
          backgroundColor: 'rgba(0,0,0,0.5)',
          color: 'white',
          border: 'none',
          borderRadius: '4px',
          cursor: 'pointer',
          zIndex: 1
        }}>
          ›
        </ButtonNext>
      </CarouselProvider>
    </div>
  );
}

export default CarouselExample;
Enter fullscreen mode Exit fullscreen mode

Update your App.jsx:

// src/App.jsx
import React from 'react';
import CarouselExample from './CarouselExample';
import './App.css';

function App() {
  return (
    <div className="App">
      <CarouselExample />
    </div>
  );
}

export default App;
Enter fullscreen mode Exit fullscreen mode

This creates a basic image carousel with navigation buttons.

Understanding the Basics

Pure React Carousel uses a component-based structure:

  • CarouselProvider: Main container that manages carousel state
  • Slider: Container for slides
  • Slide: Individual slide component
  • ButtonBack/ButtonNext: Navigation buttons
  • DotGroup: Navigation dots
  • Image: Optimized image component

Key concepts:

  • naturalSlideWidth/Height: Aspect ratio of slides (used for responsive sizing)
  • totalSlides: Total number of slides
  • Slide index: Each slide needs a unique index starting from 0
  • Responsive: Automatically adjusts to container size
  • Styling: Import CSS file for default styles

Here's an example with dots and custom styling:

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

function AdvancedCarouselExample() {
  const images = [
    'https://via.placeholder.com/800x400/007bff/ffffff?text=Slide+1',
    'https://via.placeholder.com/800x400/28a745/ffffff?text=Slide+2',
    'https://via.placeholder.com/800x400/ffc107/000000?text=Slide+3',
    'https://via.placeholder.com/800x400/dc3545/ffffff?text=Slide+4'
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '800px', margin: '0 auto' }}>
      <h2>Advanced Carousel with Dots</h2>
      <CarouselProvider
        naturalSlideWidth={100}
        naturalSlideHeight={50}
        totalSlides={images.length}
        isPlaying={true}
        interval={3000}
      >
        <div style={{ position: 'relative' }}>
          <Slider>
            {images.map((image, index) => (
              <Slide key={index} index={index}>
                <img
                  src={image}
                  alt={`Slide ${index + 1}`}
                  style={{ width: '100%', height: '100%', objectFit: 'cover' }}
                />
              </Slide>
            ))}
          </Slider>
          <ButtonBack style={{
            position: 'absolute',
            left: '10px',
            top: '50%',
            transform: 'translateY(-50%)',
            padding: '10px 15px',
            backgroundColor: 'rgba(255,255,255,0.8)',
            color: '#333',
            border: 'none',
            borderRadius: '50%',
            cursor: 'pointer',
            zIndex: 1,
            fontSize: '20px',
            width: '40px',
            height: '40px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}>
            ‹
          </ButtonBack>
          <ButtonNext style={{
            position: 'absolute',
            right: '10px',
            top: '50%',
            transform: 'translateY(-50%)',
            padding: '10px 15px',
            backgroundColor: 'rgba(255,255,255,0.8)',
            color: '#333',
            border: 'none',
            borderRadius: '50%',
            cursor: 'pointer',
            zIndex: 1,
            fontSize: '20px',
            width: '40px',
            height: '40px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}>
            ›
          </ButtonNext>
        </div>
        <DotGroup style={{
          display: 'flex',
          justifyContent: 'center',
          gap: '10px',
          marginTop: '20px'
        }} />
      </CarouselProvider>
    </div>
  );
}

export default AdvancedCarouselExample;
Enter fullscreen mode Exit fullscreen mode

Practical Example / Building Something Real

Let's build a complete image gallery carousel:

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

function ImageGalleryCarousel() {
  const [currentSlide, setCurrentSlide] = useState(0);

  const images = [
    {
      src: 'https://via.placeholder.com/800x500/007bff/ffffff?text=Image+1',
      title: 'Image 1',
      description: 'Description for image 1'
    },
    {
      src: 'https://via.placeholder.com/800x500/28a745/ffffff?text=Image+2',
      title: 'Image 2',
      description: 'Description for image 2'
    },
    {
      src: 'https://via.placeholder.com/800x500/ffc107/000000?text=Image+3',
      title: 'Image 3',
      description: 'Description for image 3'
    },
    {
      src: 'https://via.placeholder.com/800x500/dc3545/ffffff?text=Image+4',
      title: 'Image 4',
      description: 'Description for image 4'
    },
    {
      src: 'https://via.placeholder.com/800x500/6c757d/ffffff?text=Image+5',
      title: 'Image 5',
      description: 'Description for image 5'
    }
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '900px', margin: '0 auto' }}>
      <h1>Image Gallery Carousel</h1>
      <CarouselProvider
        naturalSlideWidth={100}
        naturalSlideHeight={62.5}
        totalSlides={images.length}
        currentSlide={currentSlide}
      >
        <div style={{ position: 'relative', marginBottom: '20px' }}>
          <Slider>
            {images.map((image, index) => (
              <Slide key={index} index={index}>
                <div style={{ position: 'relative', width: '100%', height: '100%' }}>
                  <img
                    src={image.src}
                    alt={image.title}
                    style={{
                      width: '100%',
                      height: '100%',
                      objectFit: 'cover',
                      display: 'block'
                    }}
                  />
                  <div style={{
                    position: 'absolute',
                    bottom: 0,
                    left: 0,
                    right: 0,
                    background: 'linear-gradient(to top, rgba(0,0,0,0.7), transparent)',
                    color: 'white',
                    padding: '20px'
                  }}>
                    <h3 style={{ margin: '0 0 5px 0' }}>{image.title}</h3>
                    <p style={{ margin: 0 }}>{image.description}</p>
                  </div>
                </div>
              </Slide>
            ))}
          </Slider>
          <ButtonBack style={{
            position: 'absolute',
            left: '10px',
            top: '50%',
            transform: 'translateY(-50%)',
            padding: '10px 15px',
            backgroundColor: 'rgba(255,255,255,0.9)',
            color: '#333',
            border: 'none',
            borderRadius: '50%',
            cursor: 'pointer',
            zIndex: 1,
            fontSize: '24px',
            width: '50px',
            height: '50px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            boxShadow: '0 2px 4px rgba(0,0,0,0.2)'
          }}>
            ‹
          </ButtonBack>
          <ButtonNext style={{
            position: 'absolute',
            right: '10px',
            top: '50%',
            transform: 'translateY(-50%)',
            padding: '10px 15px',
            backgroundColor: 'rgba(255,255,255,0.9)',
            color: '#333',
            border: 'none',
            borderRadius: '50%',
            cursor: 'pointer',
            zIndex: 1,
            fontSize: '24px',
            width: '50px',
            height: '50px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            boxShadow: '0 2px 4px rgba(0,0,0,0.2)'
          }}>
            ›
          </ButtonNext>
        </div>
        <DotGroup
          style={{
            display: 'flex',
            justifyContent: 'center',
            gap: '10px',
            marginTop: '20px'
          }}
        />
      </CarouselProvider>
      <div style={{ textAlign: 'center', marginTop: '20px', color: '#666' }}>
        Slide {currentSlide + 1} of {images.length}
      </div>
    </div>
  );
}

export default ImageGalleryCarousel;
Enter fullscreen mode Exit fullscreen mode

Now create a product carousel:

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

function ProductCarousel() {
  const products = [
    { id: 1, name: 'Product 1', price: '$99', image: 'https://via.placeholder.com/300x300/007bff/ffffff?text=Product+1' },
    { id: 2, name: 'Product 2', price: '$149', image: 'https://via.placeholder.com/300x300/28a745/ffffff?text=Product+2' },
    { id: 3, name: 'Product 3', price: '$199', image: 'https://via.placeholder.com/300x300/ffc107/000000?text=Product+3' },
    { id: 4, name: 'Product 4', price: '$249', image: 'https://via.placeholder.com/300x300/dc3545/ffffff?text=Product+4' }
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '1200px', margin: '0 auto' }}>
      <h2>Product Carousel</h2>
      <CarouselProvider
        naturalSlideWidth={100}
        naturalSlideHeight={100}
        totalSlides={products.length}
        visibleSlides={3}
        step={1}
        dragEnabled={true}
      >
        <div style={{ position: 'relative' }}>
          <Slider>
            {products.map((product, index) => (
              <Slide key={product.id} index={index}>
                <div style={{
                  padding: '10px',
                  textAlign: 'center'
                }}>
                  <img
                    src={product.image}
                    alt={product.name}
                    style={{
                      width: '100%',
                      height: '250px',
                      objectFit: 'cover',
                      borderRadius: '8px',
                      marginBottom: '10px'
                    }}
                  />
                  <h3 style={{ margin: '0 0 5px 0' }}>{product.name}</h3>
                  <p style={{ margin: 0, fontWeight: 'bold', color: '#007bff' }}>{product.price}</p>
                </div>
              </Slide>
            ))}
          </Slider>
          <ButtonBack style={{
            position: 'absolute',
            left: '-50px',
            top: '50%',
            transform: 'translateY(-50%)',
            padding: '10px 15px',
            backgroundColor: '#007bff',
            color: 'white',
            border: 'none',
            borderRadius: '4px',
            cursor: 'pointer',
            zIndex: 1
          }}>
            ‹
          </ButtonBack>
          <ButtonNext style={{
            position: 'absolute',
            right: '-50px',
            top: '50%',
            transform: 'translateY(-50%)',
            padding: '10px 15px',
            backgroundColor: '#007bff',
            color: 'white',
            border: 'none',
            borderRadius: '4px',
            cursor: 'pointer',
            zIndex: 1
          }}>
            ›
          </ButtonNext>
        </div>
      </CarouselProvider>
    </div>
  );
}

export default ProductCarousel;
Enter fullscreen mode Exit fullscreen mode

Update your App.jsx:

// src/App.jsx
import React from 'react';
import ImageGalleryCarousel from './ImageGalleryCarousel';
import ProductCarousel from './ProductCarousel';
import './App.css';

function App() {
  return (
    <div className="App">
      <ImageGalleryCarousel />
      <ProductCarousel />
    </div>
  );
}

export default App;
Enter fullscreen mode Exit fullscreen mode

This example demonstrates:

  • Image gallery carousel with navigation
  • Product carousel with multiple visible slides
  • Custom navigation buttons
  • Dot indicators
  • Responsive design
  • Drag support

Common Issues / Troubleshooting

  1. Carousel not displaying: Make sure you've imported the CSS file (import 'pure-react-carousel/dist/react-carousel.es.css'). Also check that naturalSlideWidth and naturalSlideHeight are set correctly.

  2. Slides not showing: Ensure each Slide component has a unique index prop starting from 0. The totalSlides prop should match the number of slides.

  3. Aspect ratio issues: Use naturalSlideWidth and naturalSlideHeight to define the aspect ratio. For example, naturalSlideWidth={100} and naturalSlideHeight={50} creates a 2:1 aspect ratio.

  4. Navigation not working: Make sure ButtonBack and ButtonNext are inside the CarouselProvider. They need to be within the provider context to work.

  5. Multiple slides visible: Use the visibleSlides prop to show multiple slides at once. This is useful for product carousels.

  6. Drag not working: Enable drag by setting dragEnabled={true} on the CarouselProvider. This allows users to swipe/drag slides.

Next Steps

Now that you have a basic understanding of Pure React Carousel:

  • Learn about advanced carousel configurations
  • Explore autoplay and interval settings
  • Implement thumbnail navigation
  • Add touch gesture support
  • Create custom slide transitions
  • Learn about other carousel libraries (react-slick, swiper)
  • Check the official repository: https://github.com/express-labs/pure-react-carousel
  • Look for part 59 of this series for more advanced topics

Summary

You've successfully set up Pure React Carousel in your React application and created image galleries and product carousels with navigation controls. Pure React Carousel provides a simple, flexible solution for creating carousels with minimal configuration.

SEO Keywords

pure-react-carousel
React carousel component
pure-react-carousel tutorial
React image carousel
pure-react-carousel installation
React slider component
pure-react-carousel example
React carousel library
pure-react-carousel setup
React image gallery
pure-react-carousel customization
React carousel navigation
pure-react-carousel dots
React carousel slider
pure-react-carousel getting started

Top comments (0)