18 CSS Scroll Progress Bar

The modern recipe uses animation-timeline: scroll(), a CSS-only primitive that binds keyframe animations to scroll position rather than wall-clock time. The full recipe is three declarations: .progress-bar { transform-origin: left center; animation: fill linear both; animation-timeline: scroll(root block); } plus @keyframes fill { from { transform: scaleX(0) } to { transform: scaleX(1) } }. The animation is entirely off the main thread, so the progress bar cannot judder even when JavaScript is busy — a real problem with the classic scroll-event listener pattern that this replaces. Demo 01 (Top Fixed Reading Progress Bar) is the reference implementation. The catch: as of 2026, animation-timeline is Chromium-only (Chrome 115+ / Edge 115+ / Opera 101+); Safari and Firefox haven't shipped it yet. Every demo in this collection ships a JavaScript fallback for those browsers — a 30-line rAF-throttled scroll listener guarded behind CSS.supports('animation-timeline', 'scroll()') so modern engines download the fallback but never run it. Progressive enhancement without the fragility.

The trick is deriving both values from a single source of truth. Demo 04 (Scroll Progress Bar with Percentage Counter Tooltip) shows the pattern: write ONE custom property to the root on each scroll frame, then let CSS derive everything else from it. In JavaScript: const p = Math.min(1, Math.max(0, window.scrollY / (document.documentElement.scrollHeight - innerHeight))); document.documentElement.style.setProperty('--sp-04-p', p.toFixed(4)); document.documentElement.style.setProperty('--sp-04-n', Math.round(p * 100));. In CSS: bar width is scaleX(var(--sp-04-p)); percentage counter is @property --sp-04-n { syntax: '<integer>'; inherits: true; initial-value: 0 } registered at the top of the stylesheet so counter() can render it as text: .pct { counter-reset: n var(--sp-04-n) } .pct::after { content: counter(n) '%' }. Result: bar fill + percentage counter can never desync internally because they read the same source. Wrap the listener in requestAnimationFrame throttling so it fires at most once per frame, and { passive: true } so touch inertia never jitters.

Demo 05 (Scroll Progress Bar with Back-to-Top Button, Circular Morph) is the reference. The recipe: an SVG <circle> with stroke-dasharray set to its circumference (2π × r, so for r=22 that's 138.23). Animate stroke-dashoffset from full circumference down to 0 as scroll progress increases: stroke-dashoffset: calc(var(--sp-05-c) * (1 - var(--sp-05-p, 0))). The ring visually fills clockwise. Wrap the whole SVG in an <a href="#top"> — the ring becomes clickable at any progress state, and hitting the top smooth-scrolls back. Two production refinements: (1) hide the button when scroll progress is under 10% via opacity: 0; pointer-events: none so it doesn't clutter the initial view; (2) add scroll-behavior: smooth to html BUT wrap it in @media (prefers-reduced-motion: no-preference) so users who requested less motion get an instant jump. The pattern Vercel, Linear, Medium, Substack, and Ghost all ship.

Demo 08 (Container-Scoped Scroll Progress Bar Inside a Div) shows this pattern — critical for modal readers, in-page article panels, embedded docs, or scrollable code blocks. The animation-timeline: scroll() function accepts a scoping argument: scroll(nearest block) walks UP the DOM from the animated element looking for the closest ancestor that has overflow: auto / scroll and binds the timeline to that container's scroll offset. This is powerful but fragile — a stray overflow: hidden ancestor (rounded-corner clipping, for instance) becomes the target and the timeline attaches to a box that never scrolls, leaving the bar frozen at zero with no error. The safer explicit alternative: scroll-timeline: --sp-08-t block declared on the scroller you want (creates a named timeline), then animation-timeline: --sp-08-t on the progress bar (subscribes to it). Named timelines only match elements they share a parent chain with, so the same DOM-walking issue applies but you can debug it. For a fully cross-browser approach, use the JavaScript pattern: containerRef.addEventListener('scroll', () => { const p = containerRef.scrollTop / (containerRef.scrollHeight - containerRef.clientHeight); ...; }, { passive: true });. Same math, works everywhere.

Demo 09 (Multi-Section TOC Scroll Progress Tracker) is the reference. Two moving parts: (1) a sticky sidebar TOC that highlights the currently-visible section as the reader scrolls, and (2) a per-section progress indicator (small filled dot or bar) showing how much of each section has been read. Use IntersectionObserver with rootMargin: '-80px 0px -60% 0px' — top negative offset accounts for the sticky header height; bottom -60% means a section only counts as "active" when its top edge crosses into the top 40% of the viewport. On isIntersecting, add aria-current="location" to the corresponding TOC link (semantic — screen readers announce it as "current location"; NOT aria-current="page" which means "this is the current page in a navigation set"). Style off the ARIA attribute in CSS: a[aria-current="location"] { color: var(--accent); border-inline-start-color: currentColor }. For the per-section progress inside each TOC dot: track section scroll depth with a second observer that measures entry.intersectionRatio and writes it to a custom property on the dot. All 22 lines of JavaScript. Docusaurus, Mintlify, Nextra, VitePress, Astro Starlight, and MkDocs Material all ship this pattern.

Demo 13 (Signup / Onboarding Form Scroll Progress with Save-and-Restore) covers the SaaS onboarding pattern. Three save events, all rAF-throttled: (1) on scroll, save the container's scrollTop to localStorage.setItem('form-scroll', String(el.scrollTop)); (2) on every field input event, save the field's value keyed by name; (3) on beforeunload, flush pending saves. On page load, read all keys and restore — el.scrollTop = Number(localStorage.getItem('form-scroll')) for the container plus field.value = localStorage.getItem(field.name) for each field. Add a "Clear saved progress" button that calls localStorage.removeItem for all keys — required by GDPR / CCPA for users who don't want their in-progress data cached. Two important guardrails: (1) namespace localStorage keys by form ID or route (form-onboarding-scroll, not form-scroll) so multi-form pages don't collide; (2) never save password or credit card fields (violates PCI DSS + basic security hygiene — check input.type !== 'password' && input.autocomplete !== 'cc-number' before saving). Result: users who bounce mid-form return to the exact scroll position with fields prefilled — Stripe Atlas, Notion signup, Linear onboarding, and Vercel deploy-a-project all ship this.

Yes. Every demo honors prefers-reduced-motion: when the user has requested less motion, the smooth-scroll behavior falls back to instant jumps, the ambient hue-rotate / gradient-drift animations suppress, and the progress bar updates without CSS transitions. Every interactive control (back-to-top button, TOC link, form field) has a visible :focus-visible ring at 2px minimum thickness and 3:1 contrast per WCAG 2.4.13. Progress bars that duplicate the browser's own scrollbar carry aria-hidden="true" because they're decorative — announcing a scroll percentage on every scroll event to screen readers would be noise. Progress bars that carry information the scrollbar doesn't (percentage remaining, section-of-N-sections position) use role="progressbar" + aria-valuenow + aria-valuemin="0" + aria-valuemax="100" and update aria-valuenow from the scroll listener. Core Web Vitals: all 18 use compositor-only CSS properties (transform: scaleX(), not width: X%) for the fill animation, so no layout thrash. requestAnimationFrame throttling keeps scroll listeners under one execution per frame — nothing measurable on INP even during rapid trackpad flicks. Zero CLS impact (progress bars are fixed-position elements that reserve zero layout space). Zero LCP impact (they render after the first paint of real content).

The CSS ports unchanged — every .sp-NN selector, every @property registration, every keyframe is framework-agnostic. What changes is where the JavaScript listener lives. React: useEffect(() => { const cleanup = init(); return cleanup; }, []) at the app-shell level so the listener registers once on mount and removes on route change — never re-register on every render. Vue 3: onMounted(() => init()) + onBeforeUnmount(() => cleanup()) for the same lifecycle. Svelte: onMount(() => { init(); return cleanup }). Next.js App Router: mark the scroll-progress component with 'use client' — scroll position is a browser primitive, no SSR value. Astro: use a client:only="react" or client:load directive on the component. Tailwind CSS: the pattern is mechanical translation — fixed top-0 h-1 w-full bg-transparent for the track, h-full origin-left scale-x-0 for the fill, plus a custom-property token in your @theme block: @theme { --animate-progress: sp-01 linear both; @keyframes sp-01 { from { transform: scaleX(0) } to { transform: scaleX(1) } } }. Demo 14 (Tailwind CSS Scroll Progress Bar) is the reference for Tailwind v4 with @theme + arbitrary values. Every demo's JS is written as a plain init function (15-40 lines) — strip the IIFE wrapper and call from your framework's mount hook. Zero library dependencies.