react-carousel
A pure extendable React carousel, powered by Brainhub (craftsmen who ❤️ JS)
Live code demo |
v1 migration guide |
Hire us
[](https://circleci.com/gh/brainhubeu/react-carousel)
[](https://github.com/brainhubeu/react-carousel/commits/master)
[](https://github.com/brainhubeu/react-carousel/blob/master/LICENSE.md)
[](http://makeapullrequest.com)
[](https://renovatebot.com/)
[](https://coveralls.io/github/brainhubeu/react-carousel?branch=master)
[](https://www.npmjs.com/package/@brainhubeu/react-carousel)
[](https://github.com/brainhubeu/react-carousel/commits/master)
[](https://www.npmjs.com/package/@brainhubeu/react-carousel)
[](https://www.npmjs.com/package/@brainhubeu/react-carousel)
[](https://github.com/brainhubeu/react-carousel/graphs/contributors)
## Table of Contents
- 🔌 [Installation](#installation)
- 🐥 [Usage](#usage)
- 🔨 [Props](#props)
- 🎠 [Carousel Props](#carousel-props)
- 🐾 [Dots Props](#dots-props)
- 😻 [Contributing](#contributing)
- 💁 [Setting up local development](#setting-up-local-development-which-means-running-the-docsdemo-locally)
- 🐞 [Tests](#tests)
- 🏋️ [Workflow](#workflow)
- 🏷 [Labels](#labels)
- 📝 [Decision Log](#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](https://reactjs.org/docs/uncontrolled-components.html)), 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](https://github.com/zeit/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).
```js
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.
```javascript
import React from 'react';
import Carousel from '@brainhubeu/react-carousel';
import '@brainhubeu/react-carousel/lib/style.css';
const MyCarousel = () => (
);
export default MyCarousel;
```
[](https://brainhubeu.github.io/react-carousel/docs/examples/simpleUsage)
### Showing dots or thumbnails
There is a separate Dots component that can be used to fully control navigation dots or add thumbnails.
```javascript
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 (
);
};
export default MyCarouselWithDots;
```
[](https://brainhubeu.github.io/react-carousel/docs/examples/thumbnails)
## Props
You can access a clickable demo with many examples and a [live code editor](https://brainhubeu.github.io/react-carousel/) by clicking on a Prop name.
### Carousel props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| [**value**](https://brainhubeu.github.io/react-carousel/docs/examples/controlled) | *Number* | `undefined` | Current slide's index (zero based, depends on the elements order) |
| [**onChange**](https://brainhubeu.github.io/react-carousel/docs/examples/controlled) | *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**](https://brainhubeu.github.io/react-carousel/docs/examples/animation) | *Number* | `500` | Determines transition duration in milliseconds |
| [**draggable**](https://brainhubeu.github.io/react-carousel/docs/examples/draggable) | *Boolean* | `true` | Makes it possible to drag to the next slide with mouse cursor |
| [**breakpoints**](https://brainhubeu.github.io/react-carousel/docs/examples/responsive) | *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**](https://brainhubeu.github.io/react-carousel/docs/plugins/plugins)
### Dots props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| [**value**](https://brainhubeu.github.io/react-carousel/docs/examples/dots) | *Number* | slide position in the slides Array | Current `Carousel` value |
| [**onChange**](https://brainhubeu.github.io/react-carousel/docs/examples/dots) | *Function* | `undefined` | `onChange` callback (works the same way as `onChange` in `Carousel` component) |
| [**number**](https://brainhubeu.github.io/react-carousel/docs/examples/dots) | *Number* | Amount of slides | Number of slides in the carousel you want to control |
| [**thumbnails**](https://brainhubeu.github.io/react-carousel/docs/examples/thumbnails) | *Array of ReactElements* | `undefined` | Array of thumbnails to show. If not provided, default dots will be shown |
| [**rtl**](https://brainhubeu.github.io/react-carousel/docs/examples/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
```
### Workflow
See [the Workflow subsection in our docs](https://brainhubeu.github.io/react-carousel/docs/contributions-guide/workflow)
### Labels
See [the Labels subsection in our docs](https://brainhubeu.github.io/react-carousel/docs/contributions-guide/labels)
### Decision log
See [the Decision log subsection in our docs](https://brainhubeu.github.io/react-carousel/docs/contributions-guide/decision-log)
## License
react-carousel is copyright © 2018-2020 [Brainhub](https://brainhub.eu/?utm_source=github). It is free software and may be redistributed under the terms specified in the [license](LICENSE.md).
## 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](https://github.com/brainhubeu).
[](https://brainhub.eu/?utm_source=github)
We love open-source JavaScript software! See our other projects or hire us to build your next web, desktop and mobile application with JavaScript.