<div class="progress-bar" id="progress"></div>

<article class="content">
  <h1>Scroll Progress Bar</h1>
  <p class="lead">Scroll down to see the gradient progress bar fill at the top of the page. It tracks how far through the article you are in real time.</p>

  <h2>Why reading progress matters</h2>
  <p>A scroll progress indicator gives readers immediate feedback on how far through a piece of content they are. On long-form articles, documentation pages, or tutorials, this single UI element reduces uncertainty — the reader always knows how much is left and is more likely to continue rather than abandon the page mid-way.</p>
  <p>Studies on reading behavior consistently show that users are more likely to complete content when they have a visible progress signal. The pattern is borrowed from e-readers and podcast apps, where progress has always been a first-class concern, and it translates naturally to the web.</p>

  <h2>How it works</h2>
  <p>The implementation listens to the <code>scroll</code> event on the document. On each scroll, it calculates the current percentage as <code>scrollTop / (scrollHeight - clientHeight) × 100</code>. The result is applied to the <code>width</code> of a fixed-position bar at the top of the viewport.</p>
  <p>The bar uses <code>position: fixed</code> with <code>top: 0</code> and a high <code>z-index</code> so it always sits above the page content. The gradient is applied via the <code>background</code> property — a linear gradient from indigo to violet to pink — which stays visually interesting as it grows.</p>
  <p>A subtle <code>transition: width 0.1s linear</code> smooths out the movement without introducing any perceivable lag. Without the transition, the bar can feel jittery on trackpad scrolling where events fire in small increments.</p>

  <h2>Performance considerations</h2>
  <p>The <code>scroll</code> event fires at very high frequency — potentially hundreds of times per second on smooth-scrolling devices. For a simple width update this is not a problem, but if you are doing more expensive work (DOM queries, layout reads, complex calculations), wrap the handler in <code>requestAnimationFrame</code> to throttle it to the display refresh rate.</p>
  <p>An alternative is to use <code>IntersectionObserver</code> on sentinel elements at regular intervals through the content. This approach is more performant but gives you stepped progress rather than a smooth fill — appropriate for chapter-based navigation but not for a continuous bar.</p>
  <p>For most use cases, the direct scroll listener is the right choice. Keep the handler lightweight, avoid reading layout properties inside it, and the performance is negligible.</p>

  <h2>Accessibility</h2>
  <p>Progress bars used as decorative reading indicators do not require ARIA roles since they convey no information that is not already available through the scroll position itself. However, if you want to be explicit, you can add <code>role="progressbar"</code>, <code>aria-valuenow</code>, <code>aria-valuemin="0"</code>, and <code>aria-valuemax="100"</code> and update <code>aria-valuenow</code> in the scroll handler alongside the width update.</p>
  <p>Make sure the bar has sufficient contrast against the page background. A 3px bar with a vibrant gradient on a white background comfortably exceeds WCAG AA contrast requirements for non-text elements.</p>

  <h2>Variations and extensions</h2>
  <p>You can scope the progress to a specific element rather than the full document. Instead of using <code>document.documentElement.scrollTop</code>, get the bounding rect of the content container and calculate what fraction of it has passed the viewport top. This is useful when the page has a fixed header or sticky navigation that takes up vertical space.</p>
  <p>Another popular variation places the bar at the bottom of the viewport, or inside the navigation bar itself, using it as a thin line below the nav links. This keeps it visually connected to the page chrome rather than floating independently at the very top.</p>
  <p>You can also make the color dynamic — transition the gradient based on scroll percentage, shifting from one hue to another as the reader progresses. This adds a visual layer of meaning on top of the width signal and creates a more memorable reading experience.</p>

  <h2>Browser support</h2>
  <p>The scroll event, fixed positioning, CSS gradients, and CSS transitions used in this snippet have full support across all modern browsers including Safari, Chrome, Firefox, and Edge. No polyfills are required. The <code>backdrop-filter</code> property, if you add a blur effect to the bar, requires a fallback for Firefox where support was historically limited — though modern Firefox versions support it.</p>
  <p>If you are building for older browsers, replace the gradient with a solid color and remove the transition. The core functionality — a div with a dynamically updated width — works everywhere JavaScript runs.</p>

  <h2>Integration tips</h2>
  <p>In React or Vue, set up the scroll listener in a <code>useEffect</code> or <code>mounted</code> hook and clean it up on unmount to avoid memory leaks. Store the percentage in state or a ref — a ref is preferable here since you only need to update the DOM, not trigger a re-render. Use a callback ref on the bar element and update its <code>style.width</code> directly for the best performance.</p>
  <p>In a Next.js app, add the listener in a layout component so it persists across route changes. Be aware that in single-page apps, the scroll position may not reset on navigation — add a <code>scrollTo(0, 0)</code> call on route change if you want the bar to reset at the top of each new page.</p>
  <p>That covers everything you need to build, customize, and integrate a scroll progress bar. The snippet above is self-contained and ready to copy into any project.</p>
</article>

* { box-sizing: border-box; margin: 0; padding: 0; }
body { font-family: system-ui, sans-serif; background: #f8fafc; }

.progress-bar {
  position: fixed;
  top: 0; left: 0;
  height: 3px;
  background: linear-gradient(90deg, #6366f1, #8b5cf6, #ec4899);
  width: 0%;
  transition: width 0.1s linear;
  z-index: 999;
}

.content {
  max-width: 680px;
  margin: 0 auto;
  padding: 48px 24px 120px;
}

h1 { font-size: 32px; font-weight: 800; color: #1e293b; margin-bottom: 12px; line-height: 1.2; }
h2 { font-size: 19px; font-weight: 700; color: #1e293b; margin: 32px 0 12px; }
p  { font-size: 15px; color: #475569; line-height: 1.8; margin-bottom: 14px; }
p.lead { font-size: 17px; color: #334155; margin-bottom: 32px; }
code { font-family: monospace; font-size: 13px; background: #e2e8f0; border-radius: 4px; padding: 1px 5px; color: #4f46e5; }

const bar = document.getElementById('progress');
document.addEventListener('scroll', () => {
  const doc = document.documentElement;
  const pct = (doc.scrollTop / (doc.scrollHeight - doc.clientHeight)) * 100;
  bar.style.width = pct + '%';
});