react-carousel

A pure extendable React carousel, powered by Brainhub (craftsmen who ❤️ JS)

Live code demo | v1 migration guide | Hire us

🔌 Installation
🐥 Usage
🔨 Props
- 🎠 Carousel Props
- 🐾 Dots Props
😻 Contributing
- 💁 Setting up local development
- 🐞 Tests
- 🏋️‍ Workflow
- 🏷 Labels
- 📝 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

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 },
);

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 from 'react';
import Carousel from '@brainhubeu/react-carousel';
import '@brainhubeu/react-carousel/lib/style.css';

const MyCarousel = () => (
  <Carousel plugins={['arrows']}>
    <img src={imageOne} />
    <img src={imageTwo} />
    <img src={imageThree} />
  </Carousel>
);

export default MyCarousel;

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'; import { useState } from 'react';

const MyCarouselWithDots = () => {
  const [value, setValue] = useState(0);

  const onChange = value => {
  setValue(value);
  }

  return (
    <div>
      <Carousel
        value={value}
        onChange={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>
  );
};

export default MyCarouselWithDots;

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
value	Number	`undefined`	Current slide's index (zero based, depends on the elements order)
onChange	Function	`undefined`	Handler triggered when current slide is about to change (e.g. on arrow click or on swipe)
slides	Array	`undefined`	Alternative way to pass slides. This prop expects an array of JSX elements
itemWidth	Number	`undefined`	Determines custom width for every slide in the carousel
offset	Number	`0`	Padding between items
animationSpeed	Number	`500`	Determines transition duration in milliseconds
draggable	Boolean	`true`	Makes it possible to drag to the next slide with mouse cursor
breakpoints	Object	`undefined`	All props can be set to different values on different screen resolutions

Plugins

You can extend react-carousel default behavior by applying plugins shipped within carousel

Plugins documentation

Dots props

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

Setting up local development which means running the docs/demo locally:

git clone https://github.com/brainhubeu/react-carousel
cd react-carousel
yarn
yarn start-demo
open http://localhost:8000/

Tests

Each test command should be run from the root directory.

Unit tests

yarn test:unit:coverage

E2E tests

yarn test:e2e

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.

morawskiOZ/react-carousel