scroll-depth-progress

Lightweight React hook plus an optional fixed top progress bar so readers can see how far they are through the page.

Install

npm install @lookworld4/scroll-depth-progress

Peer dependencies: react and react-dom ≥ 16.8.

Usage

Bar at the top (simplest)

Render once near the root of your app or layout:

import { ScrollProgressBar } from '@lookworld4/scroll-depth-progress';

export function Layout({ children }) {
  return (
    <>
      <ScrollProgressBar />
      {children}
    </>
  );
}

Hook only

import { useScrollDepthProgress } from '@lookworld4/scroll-depth-progress';

export function CustomIndicator() {
  const progress = useScrollDepthProgress();
  return <meter value={progress} min={0} max={1} />;
}

progress is a number from 0 (top) to 1 (bottom of scrollable content).

Scrollable panel (not the window)

Pass the element that scrolls:

import { useRef, useState } from 'react';
import { ScrollProgressBar } from '@lookworld4/scroll-depth-progress';

export function Reader() {
  const [root, setRoot] = useState<HTMLDivElement | null>(null);

  return (
    <>
      <ScrollProgressBar scrollRoot={root} height={4} />
      <div
        ref={setRoot}
        style={{ height: 400, overflow: 'auto' }}
      >
        {/* long content */}
      </div>
    </>
  );
}

ScrollProgressBar props

| Prop | Default | Description | |------|---------|-------------| | height | 3 | Thickness in px | | color | violet → pink gradient | CSS background for the fill | | zIndex | 9999 | Stacking order | | scrollRoot | (window) | Optional scroll container | | enabled | true | Turn listeners off when false |

The bar uses transform: scaleX(progress) for smooth, GPU-friendly updates.

License

MIT