React Alice Carousel

React Alice Carousel is a React component for building content galleries, content rotators and any React carousels.

👉  Live demo (API): v2.x.x

👉  Previous version (API): v1.x.x

Features

• Auto Height
• Auto Play
• Auto Width
• Custom animation modes
• Custom rendered slides
• Infinite loop
• Lazy loading
• Mobile friendly
• Multiple items in the slide
• Responsive design
• Stage padding
• Show / hide anything (indicators, arrows, slides indexes)
• Swipe to slide
• Server side rendering friendly
• Touch and Drag support
• TypeScript

Installation

npm i react-alice-carousel

Style import

# CSS
@import "react-alice-carousel/lib/alice-carousel.css";

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

Usage

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 src="https://raw.githubusercontent.com/maxmarinich/react-alice-carousel/HEAD/path-to-img" onDragStart={handleDragStart} role="presentation" />,
	<img src="https://raw.githubusercontent.com/maxmarinich/react-alice-carousel/HEAD/path-to-img" onDragStart={handleDragStart} role="presentation" />,
	<img src="https://raw.githubusercontent.com/maxmarinich/react-alice-carousel/HEAD/path-to-img" onDragStart={handleDragStart} role="presentation" />,
];

const Gallery = () => <AliceCarousel mouseTracking items={items} />;

Options

• activeIndex : Number, default 0 - Set carousel at the specified position.

• animationDuration: Number, default 400 - Set duration of animation.

• animationEasingFunction: String or Function, default ease - Property sets how an animation progresses through the duration of each cycle.

• animationType: String(slide, fadeout), default slide - Set type of animation.

• autoHeight: Boolean, default false - Set auto height mode.

• autoWidth: Boolean, default false - Set auto width mode.

• autoPlay: Boolean, default false - Set autoplay mode.

• autoPlayControls: Boolean, default false - Show/hide play/pause buttons.

• autoPlayDirection: String(ltr, rtl), default ltr - Set autoplay direction value.

• autoPlayInterval: Number, default 400 - Set autoplay interval value.

• autoPlayStrategy: String(default, action, all, none) - Set a strategy for autoplay mode

  • default - pause automatic playback on the hover
  • action - stop automatic playback if user action was detected
  • all - merge default && action strategies
  • none - ignore any user actions when the autoPlay property was specified

• controlsStrategy: String (default, responsive, alternate or combined string "default,alternate") - Set a strategy for gallery controls.

  • default - use controls as is
  • alternate - show each dot for each slide
  • responsive - navigation will be hidden if the number of gallery elements is equal to the number of items in the slide.

• disableButtonsControls: Boolean, default false - Disable buttons controls.

• disableDotsControls: Boolean, default false - Disable dots controls.

• disableSlideInfo: Boolean, default true - Disable information about current slide.

• infinite: Boolean, default false - Set infinite mode.

• innerWidth: Number, default 0 - Set a static value for a breakpoint(key) of the "responsive" property. For example, if you can't use 'window.innerWidth' during SSR.

• items: Array, default undefined - Set gallery items, preferable to use this property instead of children.

• keyboardNavigation: Boolean, default false - Enable keyboard navigation

  • ArrowLeft - go to the prev slide
  • ArrowRight - go to the next slide
  • Space - run/stop autoplay mode if autoPlay property is equal true

• mouseTracking: Boolean, default false - Enable mouse drag animation. Consider the problem with links, see the example of using the <Link/> component below.

• paddingLeft: Number, default 0 - Set the gallery offset from the left.

• paddingRight: Number, default 0 - Set the gallery offset from the right.

• renderKey: Number, default undefined - Auxiliary property, allows call the render method without changing the state inside the gallery instance.

• responsive: Object, default undefined - The key is the breakpoint (default is the result of: () => window.innerWidth or innerWidth property if the last presented).

  • items - set number of items in the slide. Default: 1

  • itemsFit: one of (contain | fill | undefined) - defines, how item should fill the container according slide's width. Default: fill.

    If contain is specified, the gallery will use the value from the items property to determine the width of the element for each slide and fill in the empty space as needed.

        {
          0: {
              items: 1,
          },
          1024: {
              items: 3,
              itemsFit: 'contain',
          }
        }
  

• syncStateOnPropsUpdate: Boolean, default true - Sync some props (like activeIndex) with carousel state while new props passed. This allows you to avoid resetting the carousel position while updating the props (e.g.: children or items).

• swipeDelta: Number, default 20 - Set minimum distance to the start of the swiping (px).

• swipeExtraPadding: Number, default 200 - Set maximum distance from initial place before swipe action will be stopped (px).

• ssrSilentMode: Boolean, default true - Disable classnames modifiers for server side rendering.

• touchTracking: Boolean, default true - Enable touch move animation.

• touchMoveDefaultEvents: Boolean, default true - Enable touch move default events on swiping. If false was specified, this prevents vertical scrolling of the parent elements during the swipe.

• onInitialized(e: EventObject): Function - Fired as callback after the gallery was created.

• onResizeEvent(e: Event): Function, default shouldProcessResizeEvent method - Fired during the "resize" event to determine whether to call the event handler. Default method checks is the root element width has changed.

• onResized(e: EventObject): Function - Fired as callback after the gallery was resized.

• onUpdated(e: EventObject): Function - Fired as callback after updating the gallery props.

• onSlideChange(e: EventObject): Function - Fired before the event object changes.

• onSlideChanged(e: EventObject): Function - Fired after the event object was changed.

• renderSlideInfo(e: SlideInfo): Rendering function - create a custom component.

• renderDotsItem(e: DotsItem): Rendering function - create a custom component.

• renderPrevButton({ isDisabled }): Rendering function - create a custom component.

• renderNextButton({ isDisabled }): Rendering function - create a custom component.

• renderPlayPauseButton({ isPlaying }): Rendering function - create a custom component.

Methods (Refs example)

• slidePrev(e: Event) => void : Go to the prev slide.
• slideNext(e: Event) => void : Go to the next slide.
• slideTo(activeIndex?: number) => void : Go to the specified slide.

Components (Links example)

• <Link /> : allows properly handle click and drag events when mouseTracking enabled, extends base HTMLAnchorElement

import React from 'react';
import AliceCarousel, { Link } from 'react-alice-carousel';
import 'react-alice-carousel/lib/alice-carousel.css';

const Gallery = () => {
  return (
    <AliceCarousel mouseTracking>
      <Link href="#">
        <img src="https://raw.githubusercontent.com/maxmarinich/react-alice-carousel/HEAD/path-to-image" />
      </Link>
    </AliceCarousel>
  );
};

Types

type EventObject = {
	item: number;
	slide: number;
	itemsInSlide: number;
	isPrevSlideDisabled: boolean;
	isNextSlideDisabled: boolean;
	type: EventType;
};

type SlideInfo = {
	item: number;
	itemsCount: number;
};

type DotsItem = {
	isActive: boolean;
	activeIndex: number;
};

enum EventType {
	ACTION = 'action', // used if a general user action (button click or swipe)
	INIT = 'init', // used if the initial event was triggered
	RESIZE = 'resize', // used if the gallery size was changed
	UPDATE = 'update', // used if the gallery was updated with props
}

CSS classes

.alice-carousel
	.alice-carousel__stage
	.alice-carousel__stage-item
	.alice-carousel__prev-btn
	.alice-carousel__prev-btn-item
	.alice-carousel__next-btn
	.alice-carousel__next-btn-item
	.alice-carousel__play-btn
	.alice-carousel__play-btn-item
	.alice-carousel__dots
	.alice-carousel__dots-item
	.alice-carousel__slide-info
	.alice-carousel__slide-info-item;

CSS modifiers

.alice-carousel.__ssr
	.alice-carousel__stage-item.__active
	.alice-carousel__stage-item.__cloned
	.alice-carousel__stage-item.__target
	.alice-carousel__next-btn-item.__inactive
	.alice-carousel__prev-btn-item.__inactive
	.alice-carousel__play-btn-item.__pause
	.alice-carousel__dots-item.__active
	.alice-carousel__dots-item.__custom
	.alice-carousel__slide-info-item.__separator;

Build the project locally

Clone

git clone https://github.com/maxmarinich/react-alice-carousel
cd react-alice-carousel

Run

npm ci
npm start

Test

npm test

License

MIT