@ouvarov/scroll-parallax

One React component for scroll-driven animation. Translate, opacity, scale, rotate — all four scroll-animatable CSS properties in one component, under 1 KB gzipped per imported component. Plus <FadeOnView> and <RevealOnView>, one-tag wrappers for the common reveal-on-scroll cases, <ScrollProgress>, a page-level reading-progress bar, and <StickyShrink>, a sticky header that shrinks on scroll. The animation itself is pure CSS animation-timeline: view() (or scroll() for the page-level ones).

📺 Live demo & docs: https://ouvarov.github.io/scroll-parallax/

JS:   2.9 KB raw  /  1.2 KB gzipped  (all components; tree-shakes to 268–869 B per component)
CSS:  8.3 KB raw  /  1.9 KB gzipped

Install

npm i @ouvarov/scroll-parallax

Use

import { Parallax } from "@ouvarov/scroll-parallax";

export function Hero() {
  return (
    <Parallax amplitude={30}>
      <img src="/hero.jpg" alt="" />
    </Parallax>
  );
}

The CSS is auto-imported by the component — one line is all you need. The image drifts from +30px to -30px on the Y axis as it passes through the viewport. No useEffect, no IntersectionObserver, no scroll listener.

Custom start and end

<Parallax from={40} to={-20}>
  <img src="..." />
</Parallax>

Pulse — three-stop animation

Pass mid to drift in, then back out. Same trick for opacity (opacityMid).

<Parallax mid={0} from={40} to={40} opacityFrom={0} opacityMid={1} opacityTo={0}>
  <Card />
</Parallax>

Card translates from +40px to 0 then back to +40px, fading in at the apex and out again — a classic "rise and settle" pulse.

Scale and rotate

<Parallax amplitude={0} scaleFrom={0.8} scaleTo={1} rotateFrom={-4} rotateTo={0}>
  <img src="..." />
</Parallax>

rotateFrom / rotateTo take degrees as numbers. Scale is a unitless multiplier (1 = original size).

Opacity ramp

<Parallax amplitude={0} opacityFrom={0.2} opacityTo={1}>
  <img src="..." />
</Parallax>

Stagger — cascade across children

Set stagger and <Parallax> stops animating itself — instead each direct child runs the animation in a cascade. No mapping over children, no JS: each child's animation-range-start is shifted by an :nth-child rule.

<Parallax stagger={6} range="cover 0% cover 50%"
          from={40} to={0} opacityFrom={0} opacityTo={1}>
  {items.map((i) => <Card key={i} />)}
</Parallax>

range is the cascade window — you decide where the reveal lands. The cascade offsets each child's start inside it; the end is shared, so every child finishes at the same point. cover 50% is the viewport center, so the group is fully revealed by the time it's in the reading zone — not only at the very top (cover 100%). With stagger, give range in the explicit "<name> n% <name> n%" form (default cover 0% cover 50%).

The cascade unit is a percentage of view progress per child, not milliseconds — scroll-driven animations ignore time-based animation-delay. Child n starts at from + (n−1) × stagger%. Works best on a group that enters together (a row or grid). Pure CSS, capped at 24 children (beyond that they share the last offset); keep from + stagger × count under the range end.

Compose everything

<Parallax
  amplitude={80}
  axis="y"
  opacityFrom={0.3}
  opacityTo={1}
  scaleFrom={0.95}
  scaleTo={1}
  range="entry 0% cover 60%"
  easing="cubic-bezier(0.7, 0, 0.3, 1)"
>
  <img src="..." />
</Parallax>

FadeOnView — the common case

Fade in as the element enters the viewport. No opacity props, no range to remember.

import { FadeOnView } from "@ouvarov/scroll-parallax";

<FadeOnView>
  <Card />
</FadeOnView>

This is exactly <Parallax opacityFrom={0} opacityTo={1} range="entry">. Pass rise for an upward drift on the way in:

<FadeOnView rise={24}>
  <Card />
</FadeOnView>

The card starts 24px lower and settles as it fades. rise={0} (the default) is a pure fade.

RevealOnView — animate in at a threshold

The element stays hidden until it reaches a trigger line on the way up — by default the lower third — then plays a short ease-out reveal and holds. Where FadeOnView ramps across the whole entry, RevealOnView waits at the threshold, then reveals over a brief span.

import { RevealOnView } from "@ouvarov/scroll-parallax";

<RevealOnView>            {/* opacity 0 → 1, starting at 30% up */}
  <Card />
</RevealOnView>

<RevealOnView effect="scale">   {/* scale 0 → 1 */}
  <Card />
</RevealOnView>

<RevealOnView effect="both" threshold={0.5} span={0.1}>   {/* snappy grow + fade at center */}
  <Card />
</RevealOnView>

threshold={0.3} with span={0.15} maps to range="cover 30% cover 45%" — invisible below 30% of the pass, animating in across the next 15%, solid after. Shrink span for a snappier entrance.

It's still a scroll-driven animation: at normal scroll speed it reads as an entrance, but scrubbing slowly tracks the scroll, and it's reversible (scroll back up past the line and it hides again). A time-based one-shot would need JS, which this package deliberately avoids.

ScrollProgress — page reading bar

A fixed bar that fills as the whole page scrolls. Drop one tag at the root of your app — no scroll listener, no useState. Unlike the rest of the library it tracks the document with animation-timeline: scroll(), not a single element's view().

import { ScrollProgress } from "@ouvarov/scroll-parallax";

<ScrollProgress />                                  {/* 4px bar at the top, currentColor */}

<ScrollProgress height={6} color="#7c3aed" />       {/* thicker, accent color */}

<ScrollProgress position="bottom" />                {/* pin to the bottom edge */}

The fill is a composite-only scaleX, so the bar rides the compositor and never lays out or paints while you scroll. It stays active under prefers-reduced-motion — it mirrors the native scrollbar rather than adding decorative motion.

StickyShrink — header that shrinks on scroll

A position: sticky header that shrinks from a tall variant to a compact one over the first distance px of page scroll. No scroll listener, no useScroll.

import { StickyShrink } from "@ouvarov/scroll-parallax";

<StickyShrink>                              {/* 80px → 56px over 200px of scroll */}
  <Logo />
  <Nav />
</StickyShrink>

<StickyShrink from={120} to={64} distance={300}>
  <Header />
</StickyShrink>

It's driven by a single registered progress variable, --ouvarov-sticky-progress (0 → 1), animated on animation-timeline: scroll(root block). Children inherit it, so they can react to the same scroll without any extra wiring:

<StickyShrink>
  {/* logo scales down as the header collapses */}
  <img style={{ scale: "calc(1 - 0.25 * var(--ouvarov-sticky-progress))" }} />
</StickyShrink>

Unlike the parallax components, shrinking a header reflows the page below it, so this one does touch layout — bounded to one element and its subtree, only while scrolling the first distance px. Under prefers-reduced-motion it stays at its tall size and never shrinks.

Props

<Parallax>

prop	type	default	notes
amplitude	number	30	Symmetric drift shortcut. Animates from +amplitude to -amplitude. Overridden by from/to.
from	number	—	Start translate in px.
mid	number	(from + to) / 2	Middle translate in px (50% keyframe). Set explicitly to create a pulse / three-stop drift.
to	number	—	End translate in px.
axis	'x' | 'y'	'y'	Which axis to drift on.
opacityFrom	number	1	Start opacity (0–1).
opacityMid	number	(opacityFrom + opacityTo) / 2	Middle opacity (50% keyframe). Set explicitly for fade-in-then-out pulses.
opacityTo	number	1	End opacity (0–1).
scaleFrom	number	1	Start scale multiplier.
scaleTo	number	1	End scale multiplier.
rotateFrom	number	0	Start rotation in degrees.
rotateTo	number	0	End rotation in degrees.
stagger	number	—	When set, the wrapper isn't animated — each direct child runs the animation, offset by this percentage of view progress per child. range sets the window; children share its end. Pure CSS via :nth-child, capped at 24 children.
range	string	'cover 0% cover 100%' ('cover 0% cover 50%' with stagger)	Any valid animation-range — where in the scroll the animation plays. With stagger, it's the cascade window (use the "<name> n% <name> n%" form); cover 50% ends at the viewport center.
easing	string	'linear'	Any valid animation-timing-function.
className	string	—	Merged onto the wrapper.
style	CSSProperties	—	Merged onto the wrapper.
children	ReactNode	—	Whatever you want to animate.

<FadeOnView>

Sugar over <Parallax>. Forwards className, style and easing unchanged.

prop	type	default	notes
rise	number	0	Upward drift in px on the way in. 0 is a pure fade.
range	string	'entry'	Where the fade plays — defaults to the element's entry into the viewport.

<RevealOnView>

Sugar over <Parallax>. Forwards className and style unchanged.

prop	type	default	notes
effect	'fade' | 'scale' | 'both'	'fade'	fade ramps opacity 0→1, scale grows from 0→1, both combines them. Eases in with ease-out.
threshold	number	0.3	Trigger line — fraction of the element's pass where the reveal starts. Below it, the element is hidden. Clamped to 0–1.
span	number	0.15	How much scroll the reveal takes after the threshold. Together: range="cover {threshold×100}% cover {(threshold+span)×100}%". Smaller = snappier.

<ScrollProgress>

Standalone page-level bar — renders its own fixed <div>, takes no children.

prop	type	default	notes
height	number | string	4	Bar thickness. Number → px; string used as-is.
color	string	currentColor	Fill color.
position	'top' | 'bottom'	'top'	Which viewport edge to pin to.
zIndex	number	2147483647	Stacking order — defaults high so it sits above page chrome.
className	string	—	Merged onto the bar.
style	CSSProperties	—	Merged onto the bar.

<StickyShrink>

A position: sticky header. Exposes --ouvarov-sticky-progress (0 → 1) to its subtree.

prop	type	default	notes
from	number | string	80	Tall height before scroll. Number → px; string used as-is.
to	number | string	56	Compact height after shrinking. Number → px; string used as-is.
distance	number | string	200	Scroll distance from the top over which it shrinks. Number → px.
className	string	—	Merged onto the header.
style	CSSProperties	—	Merged onto the header.
children	ReactNode	—	Header content. Read var(--ouvarov-sticky-progress) to react to the shrink.

The component renders a <div> wrapper. The wrapper is the animated element.

Each <Parallax> instance is scoped — values don't bleed across siblings.

Browser support

Browser	Status
Chrome / Edge / Opera	✅ 115+ (Aug 2023)
Safari	✅ 18+ (Sept 2024)
Firefox	⚠ Behind layout.css.scroll-driven-animations.enabled flag
iOS Safari	✅ 18+
Older browsers	Element renders normally, no animation

Reduced motion is respected automatically via @media (prefers-reduced-motion: reduce).

Why this exists

animation-timeline: view() has been stable in Chromium since 2023 and Safari since 2024 — the browser reads scroll progress natively, no JavaScript needed. This package is a typed React wrapper over that native CSS API.

Use without React

The React components do one thing: render an element with a class and a few CSS custom properties. All the animation lives in style.css. So you don't actually need React — import the stylesheet, add the class, set the properties. The same classes work in Vue, Svelte, Astro, or plain HTML.

Via a bundler:

import "@ouvarov/scroll-parallax/style.css";

Or in plain HTML, straight from a CDN:

<link rel="stylesheet" href="https://unpkg.com/@ouvarov/scroll-parallax/style.css">

Then use the classes directly — no build step, no JavaScript:

<!-- drifts +60px → -60px as it crosses the viewport -->
<div class="ouvarov-parallax" style="--ouvarov-parallax-from: 60px; --ouvarov-parallax-to: -60px">
  <img src="/hero.jpg" alt="">
</div>

<!-- bare class uses the defaults (+30px → -30px) -->
<div class="ouvarov-parallax"><img src="/hero.jpg" alt=""></div>

<!-- horizontal drift -->
<div class="ouvarov-parallax" data-axis="x">…</div>

<!-- page reading bar, pinned to the top -->
<div class="ouvarov-scroll-progress" data-position="top"></div>

<!-- sticky header that shrinks 80px → 56px over 200px of scroll -->
<header class="ouvarov-sticky-shrink">…</header>

These are the same class names and --ouvarov-* custom properties the React components emit — read style.css for the full set. The React layer is just typed sugar that sets them for you.

Scope

One thing, done well: translate, opacity, scale and rotate on scroll. No spring physics, no gesture handling, no layout animations — by design.

• The <Parallax> wrapper adds one DOM node. Don't want it? Skip the component and apply the .ouvarov-parallax class with the custom properties directly — the animation is pure CSS, no React required (see Use without React).

License

MIT © Olexandr Uvarov