Scroll Progress

Preview

Install

1. 1. Add the registry to components.json, once per app. Without it, the shadcn CLI looks up @txbrendan in a public list that txbrendan/ui does not control.

   npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json"

2. 2. Add the theme, once per app. It replaces your color tokens with ones checked for contrast.

   npx shadcn@latest add @txbrendan/theme

3. 3. Add the component.

   npx shadcn@latest add @txbrendan/scroll-progress

Props

• sections

  Unique section ids and labels in reading order. An empty list shows a disabled pill.

  readonly { id: string; label: string }[] · default []

• containerRef

  A mounted scrolling element. Takes precedence over containerId. Omit both to track the window.

  RefObject<HTMLElement | null>

• containerId

  The id of a mounted scrolling element, for composition without a client ref. A missing container does not track the window.

  string

• offset

  Pixels below the scroll surface's top edge at which a section becomes current. Also leaves space above a jump target.

  number · default 24

• disabled

  Stops the menu from opening. Reading progress continues to update.

  boolean · default false

• aria-label

  Names the menu. The trigger also includes the current section and the percentage read.

  string · default "Sections"

• className

  Classes for the root, merged last. Fixed at bottom center by default. Override placement for an embedded scroll surface.

  string

Accessibility

• The trigger exposes its expanded state, current section, and percentage read. Progress is not a live announcement on every scroll.
• Enter, Space, or Arrow Down opens the menu. Arrow keys, Home, End, and typing move between sections.
• Escape closes the menu and restores trigger focus. Clicking outside also closes it.
• The active section carries aria-current='location' and a filled row.
• Jump scrolling and transitions follow the theme's motion setting, including reduced motion.
• The caller supplies unique ids, meaningful labels, and semantic headings in the reading content.

Examples

import { ScrollProgress } from "@/components/ui/scroll-progress";

export default function Guide() {
  return (
    <>
      <ScrollProgress sections={[{ id: "overview", label: "Overview" }, { id: "details", label: "Details" }]} />
      <section id="overview"><h2>Overview</h2><p>Start with the essentials.</p></section>
      <section id="details"><h2>Details</h2><p>Explore the next steps.</p></section>
    </>
  );
}

"use client";
import { useRef } from "react";
import { ScrollProgress } from "@/components/ui/scroll-progress";

export default function ReadingPanel() {
  const containerRef = useRef<HTMLDivElement>(null);
  return (
    <div className="relative">
      <div ref={containerRef} className="h-96 overflow-y-auto pb-20" tabIndex={0} role="region" aria-label="Guide">
        <section id="start" className="min-h-96"><h2>Getting started</h2></section>
        <section id="next" className="min-h-96"><h2>Next steps</h2></section>
      </div>
      <ScrollProgress className="absolute" containerRef={containerRef} sections={[{ id: "start", label: "Getting started" }, { id: "next", label: "Next steps" }]} />
    </div>
  );
}