React Responsive Carousel

Common errors

• Carousel is not defined

  cause The Carousel component was not imported or was imported incorrectly.
  fix Ensure you have `import { Carousel } from 'react-responsive-carousel';` at the top of your file.

• Module not found: Error: Can't resolve 'react-responsive-carousel/lib/styles/carousel.min.css'

  cause The path to the CSS file is incorrect, or your build tool (e.g., Webpack, Vite) is not configured to process CSS imports from `node_modules`.
  fix Verify the import path `import "react-responsive-carousel/lib/styles/carousel.min.css";`. If using a bundler, ensure you have appropriate loaders (e.g., `css-loader`, `style-loader` for Webpack) configured in your build setup.

• TypeError: Cannot read properties of undefined (reading 'length') when rendering Carousel.

  cause Often occurs when children passed to `Carousel` are not valid React elements or are `undefined`/`null`, leading to rendering issues.
  fix Ensure that all direct children passed to the `Carousel` component are valid React elements (e.g., `<div>`, `<img>`, custom components) and that there are no `null` or `undefined` values in the children array if dynamically rendered.

Warnings

• gotcha The package is in maintenance mode. The primary maintainer does not have time for active development, meaning new features are unlikely, and critical bug fixes may have delayed timelines. Consider forking or contributing if you require active development.
  Fix: Be aware of the maintenance status for long-term project planning. Evaluate community forks or alternative carousel libraries if active development and immediate support are critical.
• breaking Version 3.0.2 introduced significant changes, including adding support for free children, vertical carousels, free legends, and updating ref callbacks. Callback names were also renamed, potentially breaking existing implementations.
  Fix: Review the changelog and usage examples for v3.0.2 to adapt to the new API, especially concerning children rendering and callback names. Migrate to the new 'free children' model if applicable.
• breaking Version 2.0.0 updated React to 0.14.2 and officially dropped support for Internet Explorer 8 (IE8).
  Fix: Ensure your project uses React 0.14 or newer. If IE8 support is required, you must use version 0.1.6 or older.
• gotcha The carousel styles are not automatically included and must be imported explicitly in your application. Forgetting to do so will result in an unstyled and potentially non-functional carousel.
  Fix: Add `import "react-responsive-carousel/lib/styles/carousel.min.css";` to your entry file or the component where `Carousel` is used. Ensure your build system (e.g., Webpack, Parcel) is configured to handle CSS imports.

Install

• npm install react-responsive-carousel npm
• yarn add react-responsive-carousel yarn
• pnpm add react-responsive-carousel pnpm

Imports

• Carousel
  wrong:

  const Carousel = require('react-responsive-carousel').Carousel;

  correct:

  import { Carousel } from 'react-responsive-carousel';

  The primary component for rendering carousels. Use named import syntax.
• styles
  wrong:

  require('react-responsive-carousel/lib/styles/carousel.min.css');

  correct:

  import "react-responsive-carousel/lib/styles/carousel.min.css";

  Crucial for applying default styling. Must be imported as a side effect. Often placed early in the application or component file.
• CarouselProps

  import type { CarouselProps } from 'react-responsive-carousel';

  Import types for enhanced developer experience in TypeScript projects. The library ships its own type definitions.

Quickstart

Demonstrates basic usage of the Carousel component with three image slides and associated legends, including the mandatory CSS import.

import React, { Component } from 'react';
import ReactDOM from 'react-dom';
import "react-responsive-carousel/lib/styles/carousel.min.css"; // mandatory styles
import { Carousel } from 'react-responsive-carousel';

class DemoCarousel extends Component {
    render() {
        return (
            <Carousel>
                <div>
                    <img src="https://via.placeholder.com/600x400?text=Image+1" alt="Legend 1" />
                    <p className="legend">Legend 1</p>
                </div>
                <div>
                    <img src="https://via.placeholder.com/600x400?text=Image+2" alt="Legend 2" />
                    <p className="legend">Legend 2</p>
                </div>
                <div>
                    <img src="https://via.placeholder.com/600x400?text=Image+3" alt="Legend 3" />
                    <p className="legend">Legend 3</p>
                </div>
            </Carousel>
        );
    }
}

// Assuming a div with class 'demo-carousel' exists in your HTML
ReactDOM.render(<DemoCarousel />, document.querySelector('.demo-carousel'));