Table of Contents

• 🔌 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/[email protected]/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

react-carousel is copyright © 2018-2020 Brainhub. It is free software and may be redistributed under the terms specified in the 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.