react-responsive-carousel: a swipeable carousel with an explicit maintenance warning

The README opens with a warning, before the feature list

The structure of this README is unusual in a useful way. After the badges, before the features, there is a section titled Important, and it says that the maintainer has no time available to keep maintaining the package, asks people to sort requests within the community, says safe-looking pull requests will be merged from time to time with no commitment on timelines, and explicitly invites anyone in a hurry to fork the project and publish under another name.

That paragraph is the single most important thing in the repository. Feature lists tell you what a library does; this tells you what your upgrade path looks like.

The features themselves are the standard set for this category. Responsive behaviour, mobile friendliness, swipe to slide, and mouse emulating touch. Server side rendering compatible. Keyboard navigation. Custom animation duration. Auto play with a custom interval. Infinite loop. Horizontal or vertical direction. Content is unconstrained, with each direct child representing one slide, which means images, video or arbitrary markup all work. External controls are supported, and the customisation list covers custom thumbs, custom arrows, custom indicators, custom status and custom animation handlers.

The topics match: autoplay, carousel, gallery, keyboard-navigation, mobile, react, react-component, slider, swipe. The fork count of 620 against 2,675 stars is higher than typical, and in this project's case it may reflect exactly what the README suggests.

Usage is one import, one CSS file and one wrapper

The minimal example is a class component with three divs inside a Carousel. There is no wrapper div to configure, no child-to-slide mapping function, and no theme object.

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

class DemoCarousel extends Component {
    render() {
        return (
            <Carousel>
                <div>
                    <img src="assets/1.jpeg" />
                    <p className="legend">Legend 1</p>
                </div>

The CSS import is the one thing people forget. It is required, and the comment on that line says it requires a loader, which means a plain script tag will not work without extracting the stylesheet from the package. The README offers both alternatives in comments further down: import the styles from the same path, or link the stylesheet directly from node_modules with an HTML link tag.

Installing it is yarn add react-responsive-carousel, and the published demo page plus a Codesandbox playground are linked so you can see the range of configurations without setting anything up. There is also a Storybook instance whose example source lives in the stories directory of this repository, meaning the demos are readable code rather than screenshots.

Props cover layout, behaviour and rendering, and they are all optional

The props table is long enough to be worth reading before you decide, because the defaults are opinionated in places. axis takes horizontal or vertical and defaults to horizontal. autoPlay changes the slide automatically based on the interval prop. infiniteLoop makes going past the last item return to the first. centerMode centers the current item and sets the slide width based on centerSlidePercentage. dynamicHeight means the height of items will not be fixed, which is what you want when slides have different heights.

Two props exist specifically for accessibility. ariaLabel defines the aria-label attribute for the root carousel element, and its default is undefined, which skips the attribute from the markup rather than emitting an empty one. autoFocus forces focus on the carousel when it renders. For a component whose main interaction is a swipe gesture, keyboard navigation being in the base feature set rather than an add-on is worth noting.

The rendering hooks are renderItem, renderThumb, renderArrow, renderIndicator and renderStatus, plus renderIndicator and custom status for captions. There is a stopOnHover option, swipeable, and the interval-based autoplay. The library also handles the arrows and indicators through separate props so you can replace any of them individually rather than styling the defaults.

Because each direct child is a slide with no required shape, the component composes cleanly inside a grid or flex layout, which is the usual reason to prefer this over a more rigid gallery component.

Version 3.2.22 in the manifest, 3.2.7 in the releases

This is the detail to check before you pin anything. The package.json in the repository declares version 3.2.22. The three most recent GitHub releases are v3.2.7, v3.2.6 and v3.2.5, all published in April and May 2020, and all with empty release bodies.

So fifteen patch versions were published to npm without corresponding GitHub release tags, or the tags were never created. Either way, the GitHub releases list is not a usable changelog here, and the CHANGELOG.md file in the tree is generated by a script called auto-changelog from commit messages, with an ignore pattern for merge commits and a breaking pattern of BREAKING CHANGE:.

The maintenance signal from repository metadata is mixed too. The default branch was last pushed on 2026-09-16, which is recent, and the open issue count is 4, which is remarkably low. Yet the release history stopped in 2020. What that pattern suggests is automated publishing continuing on a branch that receives occasional community commits, with no human curating releases. The README's own warning is consistent with that reading.

Practically, this means you should read CHANGELOG.md rather than the releases page, and you should expect npm to be ahead of anything visible on GitHub.

Tooling in the repository is modern, the usage example is not

The package manifest describes a TypeScript source tree with a good deal of care. main points at lib/js/index.js and types points at lib/ts/index.d.ts, so type declarations are published separately from the JavaScript. The test script runs four stages in sequence: format:check, typecheck, jest, and jest-ssr.

The last stage is the interesting one, since it is the mechanism behind the server side rendering claim. jest-ssr runs jest with a node test environment against a file called SSR.tsx, so server rendering is verified by a test rather than asserted in the README. That is a stronger guarantee than most libraries of this size offer.

The rest of the tooling is current rather than dated. TypeScript compiles through tsconfig.json and a separate tsconfig.types.json, Storybook runs on port 9001, and there are separate build scripts for the library and for its type output. Formatting is Prettier over js, ts, tsx and json files.

Against that, the README's usage example is written for an older React. It imports ReactDOM and calls ReactDOM.render, which is the pre-React-18 API, and it uses a class component with a render method. The test suite uses an uppercase TSX filename for server rendering, which suggests the source has moved to hooks and modern JSX while the README example has not followed.

So the code in the repository is newer than the documentation for it. That is the second piece of evidence for the maintenance warning, and it is the kind of thing you find out at integration time rather than at install time.

Where the extra documentation lives

Four linked documents sit above the demo in the README, and they are the parts a reader should actually open. A Codesandbox playground for the default configuration, and a second Codesandbox for customisation. A Storybook instance. A changelog. A CONTRIBUTING.md, linked as Before contributing. And a TROUBLESHOOTING.md.

The troubleshooting document is unusual for a component of this size and suggests the component has known sharp edges. The contributing document being linked before the feature discussion rather than after is another small signal that contributions are handled carefully, which fits the README's request that people sort requests within the community.

The repository tree is tidy. Source under src, tests inside it, stories under stories, a separate codesandbox directory, and configuration files at the root including .prettierrc.json, .editorconfig, .nvmrc and .npmignore. There is a .lgtm.yml for LGTM analysis and a CNAME file pointing at the demo site.

Two things a reader should know are absent. There is no CHANGELOG entry format beyond the generated file, and there is no stated React or peer dependency version in what the README shows. For a component that renders interactive children and hooks into focus handling, the React version it expects is a legitimate question, and the repository does not answer it in the README. The manifest would, which is another reason to look there rather than relying on the documentation page.

Editorial conclusion

The library does one job well and the API surface is small enough to read in a few minutes, but the honest reason to hesitate is the README's own opening. The maintainer states plainly that there is no time available and invites you to fork it, and the version situation backs that up: the npm manifest sits at 3.2.22 while the last GitHub release is 3.2.7 from May 2020. If you adopt it, pin the version, keep the CSS import, and be ready to own it.

Frequently asked questions

Official sources

1. leandrowd/react-responsive-carousel on GitHub
2. License: MIT
3. Project website
4. README
5. Releases