A progress bar that follows the scroll position of the page or of a container.
Scroll to see the progress bar
Installation
Usage
import {
ScrollProgress,
ScrollProgressContainer,
ScrollProgressProvider,
} from '@animate-ui/react/primitives/scroll-progress';
// A scrollable container.
export function Article() {
return (
<ScrollProgressProvider>
<ScrollProgress className="h-1 bg-foreground" />
<ScrollProgressContainer className="h-96 overflow-y-auto">
…
</ScrollProgressContainer>
</ScrollProgressProvider>
);
}
// The whole page.
export function PageProgress() {
return (
<ScrollProgressProvider global>
<ScrollProgress className="fixed inset-x-0 top-0 h-1 bg-foreground" />
</ScrollProgressProvider>
);
}Animation
- The bar follows the scroll position on a spring without overshoot (stiffness 250, damping 40), so it glides instead of jumping on wheel steps.
- By default it grows in width (
mode="width", from 0 to 100%), so rounded ends keep their shape;heightdoes the same vertically.scaleXandscaleYscale it with a transform instead, from itstransform-origin(the center unless you set one, e.g.origin-left). - Scrolling never re-renders React: the bar is driven by motion values.
- Under reduced motion, the bar tracks the scroll position without easing.
API Reference
ScrollProgressProvider
| Prop | Type | Default |
|---|---|---|
global? | boolean | false |
direction? | 'vertical' | 'horizontal' | 'vertical' |
transition? | SpringOptions | { stiffness: 250, damping: 40, bounce: 0 } |
children | React.ReactNode | - |
ScrollProgress
| Prop | Type | Default |
|---|---|---|
asChild? | boolean | false |
mode? | 'width' | 'height' | 'scaleX' | 'scaleY' | 'width' |
...props? | HTMLMotionProps<'div'> | - |
ScrollProgressContainer
The scrollable element (without global). Make it scroll with overflow-y-auto.
| Prop | Type | Default |
|---|---|---|
asChild? | boolean | false |
...props? | HTMLMotionProps<'div'> | - |
useScrollProgress
Returns progress (raw, 0 to 1) and scale (smoothed) motion values, with direction, global and the containerRef.