use-carousel-hook

useCarousel

useCarousel is a React hook for adding functions to create a sliding carousel.

No styling is included, the hook returns functions to integrate into your slider to allow for full flexibility and control over the carousel you create.

Typescript definitions are included.

How to use

Call the useCarousel hook in your code. This will return the following values as an object.

Property	Type	Description
ref	React.MutableRefObject<HTMLElement>	Attach this ref to your carousel element that contains your cards/elements.
previous	(amount: number = 1) => void;	Go to the previous element in the carousel. Can set amount to decrease by, default is 1.
next	(amount: number = 1) => void;	Go to the next element in the carousel. Can set amount to increase by, default is 1.
setCurrent	(current: number) => void;	Go to a specific element index in the carousel.
reset	() => void;	Go to the beginning of the carousel.
position	{ isAtStart: boolean; isAtEnd: boolean }	Position of the carousel. Can be used to disable next/previous buttons if needed.
current	number;	The index of the current item.
inView	number[];	The indexes of the items in view.

Code example

import React from 'react';
import { useCarousel } from 'use-carousel-hook';

const Carousel: React.FC = () => {
    const { ref, previous, next, setCurrent, reset } = useCarousel();

    return (
        <div>
            <button onClick={() => previous()}>Previous</button>
            <button onClick={() => previous(2)}>Go back 2 items</button>
            <button onClick={() => next()}>Next</button>
            <button onClick={() => next(2)}>Go forward 2 items</button>
            <button onClick={() => reset()}>Reset</button>
            <button onClick={() => setCurrent(2)}>Set index to 2</button>
            /* ref will need to be cast to the correct type if using TypeScript */
            <ul ref={ref as React.RefObject<HTMLUListElement>}>
                <li>Item 1</li>
                <li>Item 2</li>
                <li>Item 3</li>
                <li>Item 4</li>
            </ul>
            <div ref={ref as React.RefObject<HTMLDivElement>}>
                <div>Item 1</div>
                <div>Item 2</div>
                <div>Item 3</div>
                <div>Item 4</div>
            </div>
            <span ref={ref as React.RefObject<HTMLSpanElement>}>
                <div>Item 1</div>
                <div>Item 2</div>
                <div>Item 3</div>
                <div>Item 4</div>
            </span>
        </div>
    );
};

export default Carousel;

Options

Option	Type	Default value
scrollBehavior	'smooth' | 'auto'	'smooth'
direction	'horizontal' | 'vertical'	'horizontal'

Options example

const { ref, previous, next } = useCarousel({ scrollBehavior: 'auto', direction: 'vertical' });

Commonjs

A commonjs build of the package can be imported using use-carousel-hook/cjs.

Changelog

[0.0.14]

• Return children length if scrollWidth or scrollHeight of carousel is 0. This makes testing easier with @testing-library/react