README

react-carousel

Feature-rich, react-way carousel component that does not suck

🔌 Installation
🐥 Usage
🔨 Props
- 🎠 Carousel Props
- 🐾 Dots Props
🐞 Tests
😻 Contributing
📝 Decision Log

Why?

There are some great carousels (like slick) that do not have real React implementations. This library provides you with carousel that is not merely a wrapper for some jQuery solution, can be used as controlled or uncontrolled element (similar to inputs), and has tons of useful features.

Installation

Basic

npm i @brainhubeu/react-carousel

Typescript

npm i @types/brainhubeu__react-carousel -D

In order to run the docs/demo locally:

cd docs-www
if you want to connect demo with the carousel source code, replace __RC_ENV__ into development in https://github.com/brainhubeu/react-carousel/blob/master/docs-www/src/globalReferences.js#L2 and remove the .babelrc file in the root directory; otherwise, it will use the carousel code installed in docs-www/node_modules
yarn develop

CDN

If you don't use any bundler like Webpack, you can add these scripts to your HTML file, body section:

<script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
<script crossorigin type="text/javascript" src="https://unpkg.com/@brainhubeu/react-carousel@1.10.62-cdn/lib/react-carousel.js"></script>

Make sure to use a version ending with -cdn.

Then, you can use the following global variables:

BrainhubeuReactCarousel
BrainhubeuReactCarouselDots
BrainhubeuReactCarouselItem
BrainhubeuReactCarouselWrapper

Usage

By default, the component does not need anything except children to render a simple carousel. Remember that styles do not have to be imported every time you use carousel, you can do it once in an entry point of your bundle.

import React, { Component } from 'react';
import Carousel from '@brainhubeu/react-carousel';
import '@brainhubeu/react-carousel/lib/style.css';

export default class MyCarousel extends Component {
  render() {
    return (
      <Carousel arrows dots>
        <img src={imageOne} />
        <img src={imageTwo} />
        <img src={imageThree} />
      </Carousel>
    );
  }
}

Showing dots or thumbnails

There is a separate Dots component that can be used to fully control navigation dots or add thumbnails.

import Carousel, { Dots } from '@brainhubeu/react-carousel';
import '@brainhubeu/react-carousel/lib/style.css';

// ...

constructor(props) {
  super(props);
  this.state = {
    value: 0,
  };
}

onChange = value => this.setState({ value });

render() {
  return (
    <div>
      <Carousel
        value={this.state.value}
        onChange={this.onChange}
      >
        <img className="img-example" src={someImage} />
        ...
        <img className="img-example" src={anotherImage} />
      </Carousel>
      <Dots
        value={this.state.value}
        onChange={this.onChange}
        thumbnails={[
          (<img key={1} className="img-example-small" src={abstractImage} />),
          ...
          (<img key={12} className="img-example-small" src={transportImage} />),
        ]}
      />
    </div>
  );
}

Props

You can access a clickable demo with many examples and a live code editor by clicking on a Prop name.

Carousel props

Prop	Type	Default	Description
addArrowClickHandler	Boolean	`undefined`	Has to be added for arrowLeft and arrowRight to work
animationSpeed	Number	`500`	Determines transition duration in milliseconds
arrowLeft	React element	`undefined`	To be used instead of the default left arrow (if you provide these custom arrows, you don't have to use arrows prop)
arrowRight	React element	`undefined`	To be used instead of the default right arrow (if you provide these custom arrows, you don't have to use arrows prop)
arrows	Boolean	`false`	Renders default arrows
autoPlay	Number	`undefined`	Slide change interval in milliseconds
breakpoints	Object	`undefined`	All props (except of `value`, `onChange`, `responsive`, `children`) can be set to different values on different screen resolutions
centered	Boolean	`undefined`	Aligned active slide to the center of the carousel
clickToChange	Boolean	`undefined`	Clicking on a slide changes current slide to the clicked one
dots	Boolean	`undefined`	Renders default dots under the carousel
draggable	Boolean	`true`	Makes it possible to drag to the next slide with mouse cursor
infinite	Boolean	`undefined`	Creates an infinite carousel width
itemWidth	Number	`undefined`	Determines custom width for every slide in the carousel
keepDirectionWhenDragging	Boolean	`undefined`	While dragging, it doesn't matter which slide is the nearest one, but in what direction you dragged
minDraggableOffset	Number	`10`	Defines the minimum offset to consider the drag gesture
offset	Number	`0`	Padding between items
onChange	Function	`undefined`	Handler triggered when current slide is about to change (e.g. on arrow click or on swipe)
rtl	Boolean	`false`	Indicating if the carousel should have direction from Right to Left (make sure to pass the `rtl` param to the `Dots` component as well)
slides	Array	`undefined`	Alternative way to pass slides. This prop expects an array of JSX elements
slidesPerPage	Number	`1`	Number of slides visible at once
slidesPerScroll	Number	`1`	Number by which value will change on scroll (autoPlay, arrow click, drag)
stopAutoPlayOnHover	Boolean	`undefined`	Determines if autoPlay should stop when mouse hover over carousel
value	Number	`undefined`	Current slide's index (zero based, depends on the elements order)

Dots props

Prop	Type	Default	Description
number	Number	Amount of slides	Number of slides in the carousel you want to control
onChange	Function	`undefined`	`onChange` callback (works the same way as `onChange` in `Carousel` component)
rtl	Boolean	`false`	Indicating if the dots should have direction from Right to Left
thumbnails	Array of ReactElements	`undefined`	Array of thumbnails to show. If not provided, default dots will be shown
value	Number	slide position in the slides Array	Current `Carousel` value

Tests

Unit tests

yarn test:unit

E2E tests

yarn test:e2e

Contributing

The GitHub issues list is our roadmap. You're more than welcome to vote:

with 👍if you like a given feature request or you'd like a given bug to be fixed
with ❤️ if you love a given feature request or fixing a given bug is critical for you
with 👎if in your opinion, a given feature would create more damages than the value provided by it or you consider a given bug to be a feature

We don't give any guarantee to fix even the most liked issues but 👍and ❤️ increase probability of fixing while 👎decreases the probability of fixing.

You're also more than welcome to:

submit a feature request
report a bug
ask a question
comment an issue, discussing the details
open a PR, fixing a given issue

Decision log

SSR

When using @brainhubeu/react-carousel with SSR (Server-side Rendering), we recommend Next.js as @brainhubeu/react-carousel currently doesn't work on the server side so it must be rendered on the client side (maybe we'll provide server-side working in the future).

import dynamic from 'next/dynamic';

const { default: Carousel, Dots } = dynamic(
 () => require('@brainhubeu/react-carousel'),
 { ssr: false },
);

License

About

react-carousel is maintained by the Brainhub development team. It is funded by Brainhub and the names and logos for Brainhub are trademarks of Brainhub Sp. z o.o.. You can check other open-source projects supported/developed by our teammates here.

We love open-source JavaScript software! See our other projects or hire us to build your next web, desktop and mobile application with JavaScript.

@defite/react-carousel

Usage no npm install needed!