Scroll Progress React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import ScrollProgress from @/components/ui/scroll-progress.

"use client"

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

const sections = [
  { id: "intro", label: "Introduction" },
  { id: "usage", label: "Usage" },
  { id: "faq", label: "FAQ" },
]

export function Demo() {
  const scrollRef = useRef<HTMLElement>(null)

  return (
    <main ref={scrollRef} className="relative h-full overflow-auto">
      <ScrollProgress
        containerRef={scrollRef}
        sections={sections}
        className="absolute"
        position="bottom-center"
      />

      <section id="intro">{/* ... */}</section>
      <section id="usage">{/* ... */}</section>
      <section id="faq">{/* ... */}</section>
    </main>
  )
}

// tracks the window with no container ref:
// <ScrollProgress sections={sections} />

Props

• sectionsdefault "[]"
  Array<{ id: string; label: string }>

  Ordered sections shown as the reader moves and listed in the menu. Each id must match an element id present in the scrolled content. Defaults to an empty list, which leaves just the ring.

• offsetdefault 120
  number

  Distance in pixels below the scroller's top edge that a section must cross to be marked active.

• sizedefault "md"
  "sm" | "md" | "lg"

  Scale of the pill, the ring and the menu rows. On touch screens the pill and every row grow to at least 44px tall so they are easy to hit.

• positiondefault "bottom-center"
  "bottom-center" | "bottom-left" | "bottom-right" | "top-center" | "top-left" | "top-right"

  Where the pill is pinned. The menu grows away from that edge, and the safe-area insets of notched phones are added on top of inset.

• insetdefault 24
  number

  Distance in pixels between the pill and the edges it is pinned to.

• showLabeldefault true
  boolean

  Shows the active section name next to the ring. Turn it off for a compact round button with just the ring.

• accentColordefault "auto"
  string

  Color of the progress ring and the active section dot, any CSS color. Auto uses the foreground color of the theme.

• trackColordefault "auto"
  string

  Color of the ring track behind the progress, any CSS color. Auto is the foreground color at 15% opacity.

• surfaceColordefault "auto"
  string

  Any CSS color for the pill and the open menu. Auto is the page background at 70% over a blur.

• textColordefault "auto"
  string

  Any CSS color for the labels, the dots, the row highlight and the ring (when accentColor and trackColor are auto). Auto is the foreground color.

• radiusdefault 26
  number

  Corner radius of the open menu in pixels. The rows follow it with a radius 12px smaller, and the closed pill is always fully round.

• triggerLabeldefault "Show sections"
  string

  Accessible name of the pill button. Screen readers hear it followed by the current section.

• currentLabeldefault "current"
  string

  The word between triggerLabel and the section name in the pill's accessible name: "Show sections, current: Pricing".

• listLabeldefault "Sections"
  string

  Accessible name of the open menu.

• containerRef
  React.RefObject<HTMLElement | null>

  Scroll container to track and scroll within. Defaults to the window when omitted.

• className
  string

  Extra classes merged onto the root wrapper, which is fixed to the viewport at the chosen position. Pass absolute to pin it inside a relative panel instead. Any other <div> attribute is passed through too.

Parts

FAQ

More React navigation components