Registry / web-framework / react-alice-carousel

react-alice-carousel

library2.9.1jsnpmunverified

React Alice Carousel is a feature-rich React component designed for creating various content galleries, slideshows, and rotators. As of version 2.9.1, it offers extensive customization, including auto height/width, autoplay with various strategies, custom animation types (slide, fadeout), infinite looping, lazy loading, and full mobile and touch/drag support. It is also server-side rendering (SSR) friendly and ships with TypeScript definitions, making it suitable for modern web applications. The library is actively maintained, with a clear distinction between its v1 and v2 APIs, indicating a commitment to evolving its feature set and internal architecture over time. The project maintains a steady release cadence for bug fixes and minor features.

web-framework

npm install react-alice-carousel

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-ALICE-CAROUS

react-alice-carousel

web-frameworkjavascriptv2.9.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AliceCarousel

✓ import AliceCarousel from 'react-alice-carousel';

✗ const AliceCarousel = require('react-alice-carousel');

AliceCarousel is the default export for the main component. While CommonJS `require` might function in some setups, ESM import is the recommended and modern practice in React applications.

Carousel Styles (CSS)

✓ import 'react-alice-carousel/lib/alice-carousel.css';

✗ @import "react-alice-carousel/lib/alice-carousel.css"; // Incorrect in JS/TS files

The core CSS styles are mandatory for the carousel to render correctly and are imported as a side effect. Ensure your bundler is configured to handle CSS imports.

Carousel Styles (SCSS)

✓ @import "react-alice-carousel/lib/scss/alice-carousel.scss";

For projects using SASS/SCSS, this `@import` directive is used within SCSS files to include the styles, allowing for easier customization. It is not typically used directly in JavaScript/TypeScript unless transpiled.

Demonstrates basic usage of React Alice Carousel with `mouseTracking`, `infinite` loop, `autoPlay`, responsive items, and custom controls strategy, using placeholder images.

import React from 'react'; import AliceCarousel from 'react-alice-carousel'; import 'react-alice-carousel/lib/alice-carousel.css'; const handleDragStart = (e) => e.preventDefault(); const items = [ <img key="1" src="https://via.placeholder.com/600x400/FF0000/FFFFFF?text=Slide+1" onDragStart={handleDragStart} role="presentation" />, <img key="2" src="https://via.placeholder.com/600x400/00FF00/FFFFFF?text=Slide+2" onDragStart={handleDragStart} role="presentation" />, <img key="3" src="https://via.placeholder.com/600x400/0000FF/FFFFFF?text=Slide+3" onDragStart={handleDragStart} role="presentation" /> ]; const Gallery = () => ( <div style={{ maxWidth: '800px', margin: '0 auto' }}> <h2>My Awesome Carousel</h2> <AliceCarousel mouseTracking items={items} responsive={{ 0: { items: 1 }, 768: { items: 2 }, 1024: { items: 3 } }} infinite autoPlay autoPlayInterval={3000} disableButtonsControls controlsStrategy="alternate" /> </div> ); export default Gallery;

Debug

Known issues

breakingVersion 2.x of React Alice Carousel introduced significant API changes compared to version 1.x. Migrating from v1 to v2 requires consulting the updated documentation and adapting prop names and component usage.

fix

Refer to the v2 API documentation (https://maxmarinich.github.io/react-alice-carousel/) for current prop definitions and usage patterns when upgrading.

affects: >=2.0.0

gotchaFailure to import the necessary CSS stylesheet (`react-alice-carousel/lib/alice-carousel.css`) will result in an unstyled carousel where items might stack vertically or behave unexpectedly. The carousel relies heavily on its default styles.

fix

Add `import 'react-alice-carousel/lib/alice-carousel.css';` to your root component or the file where you use the carousel. Ensure your build system (e.g., Webpack, Vite) is configured to process CSS imports.

affects: >=1.0.0

gotchaThe `items` prop expects an array of valid React elements. Passing an empty array, `null`, or non-element data can cause rendering errors or an empty carousel. For drag functionality on images, include `onDragStart={e => e.preventDefault()}` and `role="presentation"` for accessibility.

fix

Always provide an array of React elements to the `items` prop. For images, ensure they have `onDragStart={e => e.preventDefault()}` and `role="presentation"` for proper behavior and accessibility.

affects: >=1.0.0

gotchaThe `autoPlayStrategy` prop determines how autoplay interacts with user actions (hover, clicks). Misunderstanding its values ('default', 'action', 'all', 'none') can lead to unintended autoplay behavior, such as autoplay not pausing when expected or stopping permanently.

fix

Carefully review the documentation for `autoPlayStrategy` to select the value that aligns with your desired user interaction and autoplay behavior.

affects: >=2.0.0

Errors

Common errors & fixes

Module not found: Can't resolve 'react-alice-carousel/lib/alice-carousel.css'

The required CSS stylesheet for the carousel component has not been imported or your module resolver cannot find it.

fix

Add `import 'react-alice-carousel/lib/alice-carousel.css';` to the top of your component file or an entry point file (e.g., `App.js`, `main.tsx`).

TypeError: Cannot read properties of undefined (reading 'map') (or similar for `items` prop)

The `items` prop provided to `AliceCarousel` is either `undefined`, `null`, or not a valid array, preventing the component from iterating over the slides.

fix

Ensure the `items` prop is always an array of React elements, e.g., `items={[<div key="1">Slide 1</div>]}`. Do not pass `null` or `undefined`.

Carousel renders, but slides are stacked vertically, navigation buttons/dots are missing or unstyled, and drag-and-drop doesn't work.

The core CSS styles for React Alice Carousel are not loading or being applied correctly, often due to a missing import or a bundler configuration issue.

fix

Double-check that `import 'react-alice-carousel/lib/alice-carousel.css';` is present and correctly resolved by your build system. Inspect browser developer tools to see if the carousel's CSS rules are present and applied.

Upgrade

Version history

2.9.1latest on npm

Audit

Dependencies

reactrequiredRequired as a peer dependency for any React component.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/maxmarinich/react-alice-carousel ↗

packagehttps://www.npmjs.com/package/react-alice-carousel ↗

homepagehttps://amazingandyyy.com/react-alice-carousel/ ↗