@bogachenkov/react-scrolling-progress

React component (based on HTML <progress> element) that shows the progress of the scroll and listens to the target element height changes. It also returns useScrollProgress hook in case you want to use your own progress bar.

Installation

npm install @bogachenkov/react-scrolling-progress

or

yarn add @bogachenkov/react-scrolling-progress

Table of contents

• Basic Usage
• Properties
• State

Basic Usage

ReactScrollProgress with no configuration

By default it will be tracking for document.documentElement scroll progress.

import React from "react";
import ReactScrollProgress from "@bogachenkov/react-scrolling-progress";

const MyComponent = () => {
  ...
  return (
    <>
      <ReactScrollProgress />
      ...
    </>
  )
}

---

ReactScrollProgress with some configuration

import React, { useRef } from "react";
import ReactScrollProgress from "@bogachenkov/react-scrolling-progress";

const MyComponent = () => {
    const targetElementRef = useRef();
    return (
        <div ref={targetElementRef}>
          <ReactScrollProgress
            styles={{
              position: 'sticky',
              top: '5px',
              colors: [ '#845EC2', '#D65DB1', '#FF6F91', '#FF9671', '#FFC75F','#F9F871']
            }}
            scrollOptions={{
              targetElement: ref,
              detectByElementBottom: true
            }}
          />
          ...
        </div>
    )
}

---

useScrollProgress

import React from "react";
import { useScrollProgress } from "@bogachenkov/react-scrolling-progress";

const MyComponent = () => {
    const { targetElement, progressNumber, progressString } = useScrollProgress({
      precision: 4,
      detectByElementBottom: true,
      useTargetElement: true
    });
    return (
      <div ref={targetElement}>
        <CustomScrollBar value={progressNumber} />
        ... // OR
        <div style={{width: progressString}}></div>
      </div>
    )
}

Also you can use targetElement instead of useTargetElement and passed your own ref to it:

import React, { useRef } from "react";
import { useScrollProgress } from "@bogachenkov/react-scrolling-progress";

const MyComponent = () => {
    const targetElementRef = useRef();
    const { targetElement, progressNumber, progressString } = useScrollProgress({
      precision: 4,
      detectByElementBottom: true,
      targetElement: targetElementRef
    });
    return (
      <div ref={targetElementRef}>
        <CustomScrollBar value={progressNumber} />
        ... // OR
        <div style={{width: progressString}}></div>
      </div>
    )
}

targetElement and useTargetElement fields are mutually exclusive, so you should use only one of them.

Properties

ReactScrollProgress

• scrollOptions:

  Key	Type	Default	Description
  targetElement	React.MutableRefObject<any>	null	A ref that will be assigned to the element you want to track . By default it will be tracking scroll for document.documentElement.
  detectByElementBottom	boolean	false	If set to true, then the progress of scrolling will be equal to 100% at the moment when the bottom border of the element appears in the viewport. If set to false, then the progress will be equal to 100% only when you will scroll the whole element.

• styles:

  Key	Type	Default	Description
  height	React.CSSProperties['height']	'5px'	Height of the scrollbar
  width	React.CSSProperties['width']	'100%'	Width of the scrollbar
  position	React.CSSProperties['position']	fixed	Valid CSS-position
  top	React.CSSProperties['top']	0	CSS-position top property
  left	React.CSSProperties['left']	0	CSS-position left property
  backgroundColor	React.CSSProperties['color']	#EEEEEE	Background color of the progress bar container.
  colors	React.CSSProperties['color'][]	['#319197', '#fb7319']	Array of colors used to create the gradient-color of the progress bar. If you want only one color, just pass the array with that color.
  showStripes	boolean	true	Show/hide gradient stripes.
  showBarShadow	boolean	true	Show/hide shadows in the progress bar container

useScrollProgress

• options:

  Key	Type	Default	Description
  targetElement	React.MutableRefObject<any>	null	A ref that will be assigned to the element you want to track . By default it will be tracking scroll for document.documentElement. Cannot be used with useTargetElement
  useTargetElement	boolean	false	If set to true, the hook will return a ref that needs to be assigned to the element you want to track. Cannot be used with targetElement
  precision	number	3	Decimal places of the percentage that will be returned from hook
  detectByElementBottom	boolean	false	If set to true, then the progress of scrolling will be equal to 100% at the moment when the bottom border of the element appears in the viewport. If set to false, then the progress will be equal to 100% only when you will scroll the whole element.

State

const { progressString, progressNumber, targetElement? } = useScrollProgress(options?)

Name	Type	Description
progressString	string	The progress value represented by a string like '100%'
progressNumber	number	The progress value
targetElement	MutableRefObject<any> | undefined	A ref that needs to be assigned to the element you want to track. It will returns only if you passed useTargetElement key to options object.