Premium & Brand

Scroll Progress

A bar or ring that tracks how far a scroll container has been read.

Import

tsx

import { ScrollProgress } from "@cooud-ui/ui";

bash

npx cooud-ui add scroll-progress

Examples

Reading bar & ring

Pass a `target` ref to scope progress to a scroll container instead of the page. The `bar` variant pins to the top of the box; the `circle` variant reads the same ref so a sticky reading bar and a progress ring stay in sync.

Release notes

Scroll this panel to advance the bar above and the ring beside it. Both read from the same container ref, so they stay perfectly in sync without tracking the page itself.

tsx

function ScrollProgressDemo() {
  const ref = useRef<HTMLElement>(null);
  return (
    <div className="flex items-start gap-4">
      {/* A named <section> is a scrollable region; keep it keyboard-focusable. */}
      <section ref={ref} tabIndex={0} aria-label="Release notes, scrollable" className="relative h-64 overflow-y-auto rounded-lg border">
        <ScrollProgress target={ref} className="sticky top-0 z-10" />
        <div className="space-y-4 p-4">
          {/* …tall content… */}
        </div>
      </section>
      <ScrollProgress variant="circle" target={ref} size={48} />
    </div>
  );
}

API Reference

Generated from the component's exported types.

ScrollProgressProps

Extends HTMLAttributes<HTMLDivElement>

Prop	Type	Default	Description
`variant`	`ScrollProgressVariant`	`"bar"`	Render a thin horizontal bar or a circular ring.
`target`	`RefObject<HTMLElement \| null>`	—	The scroll container to track. When omitted, the window / document scrolling element is tracked instead.
`position`	`ScrollProgressPosition`	`"top"`	Where to pin the bar variant (ignored for the circle).
`size`	`number`	`40`	Diameter of the ring in px (circle variant only).

Reading bar & ring

Release notes

Scroll this panel to advance the bar above and the ring beside it. Both read from the same container ref, so they stay perfectly in sync without tracking the page itself.

tsx

function ScrollProgressDemo() {
  const ref = useRef<HTMLElement>(null);
  return (
    <div className="flex items-start gap-4">
      {/* A named <section> is a scrollable region; keep it keyboard-focusable. */}
      <section ref={ref} tabIndex={0} aria-label="Release notes, scrollable" className="relative h-64 overflow-y-auto rounded-lg border">
        <ScrollProgress target={ref} className="sticky top-0 z-10" />
        <div className="space-y-4 p-4">
          {/* …tall content… */}
        </div>
      </section>
      <ScrollProgress variant="circle" target={ref} size={48} />
    </div>
  );
}