React-use-carousel-hook NPM

React `useCarousel` hook 🎠

This npm package provides react components to display a carousel. The components can be loaded through a useCarousel hook. The carousel is quite simple but still supports a wide set of requirements and is easy to use.

Should I use a carousel?

Short answer, no. See shouldiuseacarousel.com for more information on this topic. If you want or have to use a carousel anyway you're more than welcome to use this one. :-)

Key features

Load multiple carousels on one page without conflicts
Easy to use Carousel, Slides, Control and Pagination components
Lightweight and zero dependencies (besides react)
Supports multiple slides per view without any custom configurations
Realized with vanilla JavaScript and CSS Scroll Snap
Accessible and automatically applied aria attributes

Installation

npm install react-use-carousel-hook
# or
yarn add react-use-carousel-hook

Usage

With react-use-carousel-hook you can easily display a carousel by importing the hook and use the returned components. There are four available components. The first one is the Carousel component which is needed to support the aria attributes. The second one is the Slides component which is used to wrap your slides. The third one is the Control component which can be used to display previous / next slide buttons. The last one is the Pagination component which can be used to display a pagination representing the carousel slides.

import { useCarousel } from 'react-use-carousel-hook';
import "react-use-carousel-hook/dist/index.css";

const YourComponent = ({ items = [] }) => {
  const { Carousel, Slides, Control, Pagination } = useCarousel();

  return (
    <Carousel>
      <Slides>
        {items.map((item) => (
          <div key={item.id}>
            <h3>{item.title}</h3>
            <p>{item.content}</p>
          </div>
        ))}
      </Slides>

      <Control direction="prev" />

      <Pagination buttonClassName="bg-gray aria-selected:bg-black" />
      {/* OR */}
      <Pagination>
        {(index) => <button className="bg-gray aria-selected:bg-black">Slide number {index}</button>}
      </Pagination>

      <Control direction="next" />
    </Carousel>
  );
};

Hook

Usage

The useCarousel hook returns four components and accpets some options as function parameter.

const { Slides } = useCarousel({ loop: false });

Options

Option	Type	Default	Description
`loop`	`boolean`	`false`	If set to false the `Control` prev/next button will be disabled when start/end of carousel is reached. If set to true buttons can always be clicked and carousel jumps to start if at end and vice versa.

Components

There are four components that can be used via the useCarousel hook. Those components are Carousel, Slides, Control and Pagination. Each of them supports or even requires a number of props.

`Carousel`

This component is needed to support the aria attributes. Its only purpose is to make the carousel accessible. You can pass anything as children.

<Carousel>
  <h2>FooBar</h2>
  <Slides>
    <div>1</div>
    <div>2</div>
    <div>3</div>
  </Slides>
</Carousel>

Prop	Type	Default	Description
children	`ReactNode`	`undefined`	Any elements. Used as wrapper for `Slides`, `Control`, `Pagination`.
			All props that are supported by the `<div/>` element.

`Slides`

Wrapper component for the slides. It will add styles to make the slides look and feel like a carousel.

<Slides>
  {[1, 2, 3, 4].map((item) => (
    <div key={item}>Slide {item}</div>
  ))}
</Slides>

Prop	Type	Default	Description
children*	`ReactElement[]`	`undefined`	The slides of the carousel.
			All props that are supported by the `<div/>` element.

* required

`Control`

This component can be used to display a previous or next slide button. To style a disabled control button use the :disabled pseudo-class in CSS.

<Control direction="prev"/>
<Control direction="next"/>

Prop	Type	Default	Description
direction*	`"prev" \\| "next"`	`undefined`	The direction in which the carousel should scroll/slide when clicked.
			All props that are supported by the `<button/>` element.

* required

`Pagination`

This component can be used to display a pagination to control the carousel slides. To style the active pagination button use the &[aria-selected=“true”] attribute selector in CSS.

Usage of basic pagination with bullets:

<Pagination buttonClassName="bg-gray aria-selected:bg-black" />

If you need more control and want to display a numbered pagination you can implement it like this:

<Pagination>
  {(index) => (
    <button className="bg-gray aria-selected:bg-black">Slide number {index}</button>
  )}
</Pagination>

Prop	Type	Default	Description
buttonClassName	`string`	`undefined`	Can be used to set classNames to the pagination buttons.
children	`(index: number) => HTMLButtonElement`	`undefined`	Will return basic button as pagination point if undefined. Button can be customized by returning a function returning a button.
			All props that are supported by the `<div/>` element.