Premium & Brand

Scroll Progress

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

Import

tsx

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

bash

npx cronus-ui add scroll-progress

Examples

.cronus

The same component declared in Cronus. Emitted at build time from the audit fixtures — the kernel renders it as HTML with no React.

PortedParity: MatchGeometry 1/1Pixel diff 0 pxLogic 1/1Parity scoreboard

default.cronus

app "audit-fixtures" {
  port 5176
}

style {
  preset aurora
  theme dark
}

component ScrollProgressDefault layout:inline style:scroll-progress {
  value:40
  aria-label:"Scroll progress"
  label "Scroll progress"
}

page "/audit/scroll-progress/default" type:custom {
  use ScrollProgressDefault
}

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).
`className`	`string`	—	Additional class names merged onto the root.
`children`	`ReactNode`	—	Contents of the component.
`id`	`string`	—	DOM id of the root element.

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>
  );
}

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>
  );
}