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="path-to-img" onDragStart={handleDragStart} role="presentation" />,
  <img src="path-to-img" onDragStart={handleDragStart} role="presentation" />,
  <img src="path-to-img" onDragStart={handleDragStart} role="presentation" />,
];

const Gallery = () => {
  return (
    <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.

• 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',
          }
        }

• 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 - Fired during the "resize" event to determine whether to call the event handler. Default result of () => true;

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

• 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

• 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.

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 (activeIndex)
}

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