react-scroll-hooks

Scrolling

Cross-browser scroll hooks to manage scrolling between react elements.

Features

• Cross Browser
• Scroll Inside Container
• Scroll Entire Document
• Simple Hook Based API
• Efficient

Hooks

• useScroll: A hook to manage the scrolling between elements.
• useScrollSequence: Includes ref management on top of useScroll. Use the createScrollRef function returned by the hook to quickly attach refs to a sequence of elements, then use next, previous and goToPosition methods to scroll between them.

useScroll Hook

The useScroll hook can be used to scroll an entire document or within a container.

Usage

import { useScroll } from 'react-scroll-hooks';
 
const Component = () => {
    const containerRef = React.useRef();
    const elementRef = React.useRef();
    const scrollSpeed = 50;
 
    const { scrollToElement, scrollToY } = useScroll({ scrollSpeed, containerRef })
 
    return (
        <div ref={containerRef} style={{ position: 'relative', overflow: 'scroll' }}>
            <button onClick={() => scrollToElement(elementRef)}
            ...
            <p ref={elementRef}></p>
        </div>
    )
}

Note: The container in which scrolling occurs requires the following CSS properties to work as expected:

position: relative;
overflow: scroll;

Props

The hook takes an object as a parameter with the following properties:

Parameter	Type	Default	Description
scrollSpeed	number	40	The speed at which scrolling occurs
containerRef	Ref	document.documentElement	A ref to the container. If a ref is not provided then it scrolls the entire document.

Returns

Property	Type	Description
scrollToElement	(ref: MutableRefObject<.HTMLElement>, verticalOffset: number) => undefined	Use this method to scroll to an element with a given ref leaving verticalOffset pixels between element and the top of the container/document.
scrollToY	(y: number) => undefined	Use this method to scroll to a y position in the container/document.

You can destructure these properties as follows:

const { scrollToElement, scrollToY } = useScroll();

useScrollSequence Hook

The useScrollSequence hook can be used to scroll through a sequence of elements using methods such as next and previous. You can scroll within a container or the entire document.

Usage

import { useScrollSequence } from 'react-scroll-hooks';
 
const Component = () => {
    const containerRef = React.useRef();
 
    const { createScrollRef, next, previous, goToPosition, active } = useScrollSequence({
        initialActive: 2,
        verticalOffset: 100,
        scrollSpeed: 50,
        containerRef
    });
 
    return (
        <div ref={containerRef} style={{ position: 'relative', overflow: 'scroll' }}>
            <button onClick={() => next()}>next</button>
            <button onClick={() => previous()}>previous</button>
            <button onClick={() => goToPosition(2)}>Go To Position 2</button>
            ...
            <p {...createScrollRef()}>Position 0</p>
            <p {...createScrollRef()}>Position 1</p>
            <p {...createScrollRef()}>Position 2</p>
        </div>
    )
}

Note: The container in which scrolling occurs requires the following CSS properties to work as expected:

position: relative;
overflow: scroll;

Props

The hook takes an object as a parameter with the following properties:

Parameter	Type	Default	Description
initialActive	number	-1	The index of the initial active element. This will scroll to the element on first render.
verticalOffset	number	0	The space between the top of the container/document and the element being scrolled to.
scrollSpeed	number	40	The speed at which scrolling occurs.
containerRef	Ref	document.documentElement	A ref to the container. If a ref is not provided then it scrolls the entire document.

Returns

Property	Type	Description
createScrollRef	() => {ref: MutableRefObject<.HTMLElement>, index: number}	This method returns a ref to attach to an element. And the index the element will be in the scroll order.
next	() => undefined	Scrolls to the next element in the sequence.
previous	() => undefined	Scrolls to the previous element in the sequence.
goToPosition	(index: number) => undefined	Scrolls to the element at the given index in the sequence.
active	number	The index of the currently active element.

You can destructure these properties as follows:

const { createScrollRef, next, previous, goToPosition, active } = useScrollSequence();