@wuyuchentr/react-scroll-progress-bar

A lightweight React hook + component that displays a gradient reading progress bar at the top of the page — like Medium.

• Auto-calculates scroll percentage
• Gradient support — custom colors and direction
• Only shows when page is scrollable
• < 1 KB gzipped

Install

npm install @wuyuchentr/react-scroll-progress-bar

Usage

Component

import { ScrollProgressBar } from '@wuyuchentr/react-scroll-progress-bar';

function App() {
  return (
    <>
      <ScrollProgressBar from="#667eea" to="#764ba2" height={3} />
      <YourPageContent />
    </>
  );
}

Hook

import { useScrollProgress } from '@wuyuchentr/react-scroll-progress-bar';

function Readometer() {
  const progress = useScrollProgress();
  return <div>{Math.round(progress * 100)}% read</div>;
}

Props (ScrollProgressBar)

| Prop | Type | Default | Description | |------|------|---------|-------------| | from | string | '#667eea' | Gradient start color | | to | string | '#764ba2' | Gradient end color | | color | string | — | Override with a custom CSS color/gradient | | height | number | 3 | Bar height in pixels | | direction | string | 'to right' | Gradient direction (e.g. 'to right', 'to left') | | show | boolean | true | Show/hide the bar | | className | string | — | CSS class | | style | object | — | Inline styles (merged) |

How it works

• Listens to window.scroll with requestAnimationFrame for smooth performance
• Calculates: scrollY / (docHeight - windowHeight)
• Hides the bar when docHeight <= windowHeight (no scrolling needed)
• Uses position: fixed and pointer-events: none so it never blocks clicks