Skip to content
VenusUI
Get started

Scroll Progress

A thin bar that fills as the reader scrolls through a page or container.

Preview

Installation

npx shadcn@latest add @venusui/scroll-progress

Run this in a project set up with shadcn. If you haven’t set it up yet, run npx shadcn@latest init first.

Files added to your project

Paths use the default shadcn aliases. The CLI follows the aliases in your components.json.

  • @/components/ui/scroll-progress.tsx

Usage

The code behind the preview above.

scroll-progress-demo.tsx

"use client"

import * as React from "react"

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

export default function ScrollProgressDemo() {
  const ref = React.useRef<HTMLDivElement>(null)
  return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border bg-card">
      <ScrollProgress target={ref} label="Article progress" />
      <div ref={ref} tabIndex={0} role="region" aria-label="Scrollable article" className="h-56 space-y-3 overflow-y-auto p-5 text-sm text-muted-foreground outline-none focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:ring-inset">
        <p className="font-medium text-foreground">Scroll inside this box</p>
        {Array.from({ length: 10 }, (_, i) => (
          <p key={i}>Paragraph {i + 1}. The bar above fills as you read further down.</p>
        ))}
      </div>
    </div>
  )
}

API reference

PropTypeDefaultDescription
targetRefObject<HTMLElement | null>—Scrollable element to track. Defaults to the page.
labelstring"Reading progress"Accessible name.
classNamestring—Classes, e.g. fixed inset-x-0 top-0 z-50.

Only the props above.

Requirements

  • React 19 and Tailwind CSS v4.

Customization

  • Pin it under your header with fixed top-14 inset-x-0.
  • The bar uses your theme’s primary color; edit bg-primary to change it.

Accessibility

  • A labelled progress bar whose aria-valuenow follows the scroll.

Troubleshooting

It stays empty.
The page (or target) must be taller than the viewport to scroll.
Unknown registry "@venusui"
Your shadcn CLI couldn’t find the namespace in the shadcn registry index. Use the latest CLI (npx shadcn@latest), install by URL, or register it with its address: npx shadcn@latest registry add @venusui=https://venusui.com/r/{name}.json.
No components.json found
Run npx shadcn@latest init in your project first.
Loading preview

Animated Tabs

Navigation

Tabs with a sliding underline and fading panels, following the WAI-ARIA tabs pattern.

Loading preview

Bar Loader

Loaders

A thin indeterminate progress bar for pages and cards that are loading.

Loading preview

Dock

Navigation

A row of icons that magnify as the mouse approaches, like the macOS dock.