madmax3365/react-carousel

🎠React carousel is a feature-rich, react-way react component that does not suck

react-carousel

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

Live code demo | Hire us

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

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

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

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

• git clone https://github.com/brainhubeu/react-carousel
• cd react-carousel
• yarn
• cd docs-www
• yarn
• 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
• open http://localhost:8000/

Tests

Each test command should be run from the root directory.

Unit tests

yarn test:unit

E2E tests

yarn test:e2e

Labels

Our issues are marked with the following labels:

• issue type (mutually exclusive):
  • bug
  • enhancement - a feature request or a proposal to improve tests or to improve README or to improve anything beside fixing a bug
  • question
• answering labels (mutually exclusive):
  • answering: reported by brainhubeu if the issue is created by any member of the brainhubeu organization with no comments by external contributors
  • otherwise answering: answered if the last comment is by a brainhubeu member
  • otherwise answering: not answered
• used by third-party GitHub apps:
  • 💵 Funded on Issuehunt - funded on IssueHunt so you can earn money, fixing the given issue
  • 🎁 Rewarded on Issuehunt - already rewarded on IssueHunt
• other labels:
  • duplicate - if the given issue is a duplicate of another issue
  • no reproduction details - if we miss details needed to reproduce the given issue
  • needs discussion - if we need to discuss details of the given issue
  • proposed issuehunt if we consider the given issue to fund on IssueHunt
  • hacktoberfest - used in Hacktoberfest during October, each year so you can obtain a T-shirt according to the Hacktoberfest rules

PRs labels:

• testing (mutually exclusive):
  • tested & works
  • tested & fails
• used by third-party GitHub apps:
  • renovate for PRs opened by Renovate
  • dependencies for PRs opened by Dependabot
• other labels:
  • wip - Work in Progress so don't merge

Labels used for both issues and PRs:

• blocked if a given issue or PR is blocked by another issue or PR

Decision log

React

We love React so we'd like to focus on React only and in the nearest future, we don't plan to make this library working in another framework like Vue.js.

Cypress

We've decided that Cypress is better than Hermione (Hermione predecessor is Gemini) because Hermione required setting a very large tolerance in order to pass both locally and in CI. Moreover, Cypress is much more popular.

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

Renovate

We've decided that Renovate is better than Greenkeeper because Renovate is very configurable and has a great support.

IssueHunt

We've decided to use IssueHunt to fund issues so we can get more contributors (more contributors, more popular a given project), assign a value to issues and reward active contributors.

Testing environment deployment

We've decided to use http://beghp.github.io/ domain to deploy each branch there because in a version deployed to Netlify we've noticed broken fonts so deploying to GitHub Pages gives an environment the most possibly similar to the production version. beghp is an acronym from Brainhub.eu GitHub Pages and we use this organization in order to keep only real repos in the brainhubeu organization.

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.