Pure React Carousel

Created By

A highly impartial suite of React components that can be assembled by the consumer to create a responsive and aria compliant carousel with almost no limits on DOM structure or CSS styles.

See Live Examples | See Example Code

---

Motivation

My goal was to create a 100% ReactJS carousel that doesn't try to impose structure or styles that need to be defeated in order to match your site's design standards. Are you tired of fighting some other developer's CSS or DOM structure? If so, this carousel is for you.

Carousels: Love them or hate them. However, if you are a React developer, and you have to use a carousel, why not use one that was...

• Developed from the ground-up in React.
• Is not a wrapper or port of some non-React carousel like Slick or Flickity.
• Fully supports touch events.
• Is ARIA compliant.
• Is responsive by default.
• Lets you assemble the carousel components in the DOM in any order you desire so long as they are all children of a single <CarouselProvider /> component.
• Lets you put any class names, properties, attributes, or styles on any of the components that you need.
• Supports ES6 and CommonJS.
• Has 100% test coverage. Solid!

Table of contents

• 🛠 Tutorial
• Component Properties (props)
• Components
  • <CarouselProvider />
  • <Slider />
  • <Slide />
  • <Dot />
  • <DotGroup />
  • <Image />
  • <ButtonBack />
  • <ButtonNext />
  • <ButtonFirst />
  • <ButtonLast />
  • <ButtonPlay />
  • WithStore() Higher Order Component
  • Hooks and useContext
• TypeScript usage
  • WithStore() Higher Order Component
  • Examples
• Dev Workflow
• Contributors

🛠 Tutorial 🛠

Let's make a simple carousel with three slides, a next button, and a back button.

1. Add the module to your project.

npm i -S pure-react-carousel

1. Import only the required components into your project.

JSX import React from 'react'; import { CarouselProvider, Slider, Slide, ButtonBack, ButtonNext } from 'pure-react-carousel';

1. Using Webpack or Rollup? Does your Webpack config have a loader for "css" files? If so, import the css as well.

JSX import React from 'react'; import { CarouselProvider, Slider, Slide, ButtonBack, ButtonNext } from 'pure-react-carousel'; import 'pure-react-carousel/dist/react-carousel.es.css';

1. Put a CarouselProvider component in your code. This allows the other carousel components to communicate with each other. The only required properties are the totalSlides, naturalSlideWidth, and naturalSlideHeight. The naturalSlideWidth and naturalSlideHeight are used to create an aspect ratio for each slide. Since the carousel is responsive by default, it will stretch to fill in the width of its parent container. The CarouselProvider must also have children. We'll add the children in the next step.

```JSX import React from 'react'; import { CarouselProvider, Slider, Slide, ButtonBack, ButtonNext } from 'pure-react-carousel'; import 'pure-react-carousel/dist/react-carousel.es.css';

export default class extends React.Component { render() { return ( ); } } ```

1. Place the components in any order you wish as long as they are children of a single CarouselProvider component. Some components have ancestor/descendant relationships but they don't have to be direct relatives. For example: Slides need to go inside of a Slider. Slides also require a sequentially numbered index prop starting at zero. Chances are, a lot of the time, you're going to be populating the slides from data and looping through the data, so it would be easy to add an index in your loop.

```JSX import React from 'react'; import { CarouselProvider, Slider, Slide, ButtonBack, ButtonNext } from 'pure-react-carousel'; import 'pure-react-carousel/dist/react-carousel.es.css';

export default class extends React.Component { render() { return ( I am the first Slide. I am the second Slide. I am the third Slide. ); } } ```

1. Add some buttons so the user can navigate forward and backwards. In order to use left/right arrow keyboard navigation, the Slider component needs to be focused. See example in the Slider section

```JSX import React from 'react'; import { CarouselProvider, Slider, Slide, ButtonBack, ButtonNext } from 'pure-react-carousel'; import 'pure-react-carousel/dist/react-carousel.es.css';

export default class extends React.Component { render() { return ( I am the first Slide. I am the second Slide. I am the third Slide. Back Next ); } } ```

That's it. You have a super basic Carousel.

There are other components you can add, like ButtonFirst, ButtonLast, an Image component, and even an ImageWithZoom component that zooms on mouse hover or finger tap.

Obviously, you can customize the heck out of the layout. If you need to bury your Slider component in 18 parent divs, go for it. It will still do its job. Feel free to add the className property to any of the Components to further customize your carousel. Or, hook into the many BEM named default CSS class names built into the carousel components.

Some components have a ancestor / descendant relationship but they don't have to be direct descendants of the parent. For example, Slide needs to be a descendant of Slider, but you can put a bunch of div wrappers around slide if you need to. A good analogy are the html tags table and tr. The tr tag needs to be a descendant of table, but it doesn't have to be a direct descendant. You can have a tbody between them in the tree.

Component Properties (props)

className

You can attach your own className property to each and every component in this library and it will be appended to the list of classes. It's appended so that it has more specificity in a tie, allowing your CSS to more easily override any internal styles without resorting to using !important.

styles

You can attach your own styles property to each component in this library, however, any styles generated by the component take precedence over any styles you provide. Some components, like the <Slider />, need their internal styles to function correctly.

event props (onClick, onFocus, onBlur, etc)

You can supply your own event callbacks to any component. Your event callbacks are called after a component's internal event handling. Basically, your callback becomes a callback to our callback. Say that 10 times fast. :-)

all other props

Any remaining props not consumed by the component are passed directly to the root element of a component unless otherwise noted in that component's documentation. This makes all the components in this library HIGHLY configurable. You can, for example, add your own event handlers, or change aria tags, etc.

Components

<CarouselProvider />

property	type	default	required	purpose
children	[string|node]		Yes	Children is a special React property. Basically, the CarouselProvider needs to wrap other Carousel components and JSX
className	[string|null]	null	No	Optional className string that will be appended to the component's className string
currentSlide	number	0	No	<Slide /> to display ONLY when CarouselProvider mounts. The indexing of <Slide /> components starts with 0. This is a poorly named variable and will be deprecated in a future version.
hasMasterSpinner	bool	false	No	When true, a spinner will cover <Slider /> component until all <Image /> and <ImageWithZoom /> are done loading images. If there are no <Image /> or <ImageWithZoom /> components, the spinner will spin until this property is set to false
interval	number	5000	No	Number of milliseconds to wait when the auto slideshow is active
isPlaying	bool	false	No	Setting this to true starts an auto slideshow. After "interval" milliseconds, the slider will move by "step" slides either forward or backwards depending on the value of "playDirection".
lockOnWindowScroll	bool	false	No	When set to true, scrolling of the carousel slides are disabled while the browser window is scrolling
naturalSlideHeight	number		Yes	The natural height of each <\Slide > component. **
naturalSlideWidth	number		Yes	The natural width of each <\Slide > component. **
orientation	string	"horizontal"	No	Possible values are "horizontal" and "vertical". Let's you have a horizontal or vertical carousel.
playDirection	['forward'|'backward' ]	'forward'	No	The direction for the auto slideshow
step	number	1	No	The number of slides to move when pressing the <ButtonBack /> and <ButtonNext /> buttons.
dragStep	number	1	No	The number of slides to move when performing a short touch drag.
tag	string	'div'	No	The HTML element to use for the provider.
totalSlides	number		Yes	Always set this to match the total number of <Slide /> components in your carousel
touchEnabled	boolean	true	No	Set to true to enable touch events
dragEnabled	boolean	true	No	Set to true to enable mouse dragging events
visibleSlides	number	1	No	The number of slides to show at once. This number should be <= totalSlides
infinite	boolean	false	No	Should the carousel continue or stop at the beginning or end of the slides
isIntrinsicHeight	boolean	false	No	Disables the enforced height ratio, and instead uses the intrinsic height of the slides. This option can only be active in horizontal orientation, it will throw an error in vertical orientation.

The CarouselProvider component creates the following pseudo HTML by default:

<props.tag|div class="carousel [props.className]" ...props>
  [props.children]
</props.tag|div>

More about naturalSlideWidth and naturalSlideHeight The carousel is responsive and by default will flex to the full width of the <Slider /> parent container. It's up to you to contain the carousel width via css. Each slide will be the same height to width ratio (intrinsic ratio). CarouselProvider needs to know the default size of each <Slide />. Note: you can make the carousel non-responsive by setting the width of <Slider /> to a fixed css unit, like pixels. There are many other ways to make the carousel non-responsive.

<Slider />

A Slider is a viewport that masks slides. The Slider component must wrap one or more Slide components.

property	type	default	required	purpose
children	[string|node]		Yes	Children is a special React property. Basically, the Slider needs to wrap other components and/or JSX
ariaLabel	string	'slider'	N	Optional