colyptus.

Software · · 1 min read

Building scroll animation without a library

Scroll-driven scenes with the Web Animations API: the method, the pitfalls, and why we added no dependency.

Building scroll animation without a library

Every movement on this site is tied to a timeline that advances as you scroll: the bud's cap lifts, roots are drawn, storyboard frames slide by. We didn't use an animation library for this; the browser's own Web Animations API was enough.

The idea: a paused animation

For each element we create an ordinary animation and pause it immediately. Then we turn scroll progress into a number between 0 and 1 and write it to the animation's currentTime. Scrolling, not time, plays the animation.

const anim = el.animate(keyframes, { duration: 1000, fill: "both" });
anim.pause();
onScroll((p) => { anim.currentTime = p * 1000; });

Progress comes down to a few patterns: as an element enters, as it crosses the screen, or inside a pinned section. In pinned sections, progress is how much of the section is behind you.

Pitfalls we hit

  • React attaches a parent's ref after the children's layout effects. Looking up the pinned section by ref returns nothing; find it in the DOM with closest().
  • When computing SVG coordinates with trigonometry, server and browser can round the last digit differently; we round values to avoid hydration mismatches.
  • Sticky positioning doesn't work inside an ancestor with overflow: hidden; use overflow-x: clip.
  • On a Turkish page, uppercased English labels become 'FİG'; we give those labels lang="en".

For everyone

The server always sends the finished state of every animation. If JavaScript doesn't load or the visitor prefers reduced motion, the page stays complete and readable. Animation is ornament; content must stand without it.

Something waiting to open?

An idea, a half-built product, a brand that needs a second life. Let's start with a short note.