🎨 CSS: Fix a Scroll-Driven Animation Running Only on First Load
A CSS scroll-driven animation using animation-timeline: scroll() computes its timeline range from the scroller’s content size at the moment the timeline attaches to an element. If content is added later — images lazy-loading in, or a list populated after an API response — the scrollable height changes, but an already-established timeline for elements that existed before that growth doesn’t get recalculated, so the animation plays correctly on a cold load and looks stuck or already-finished once a warm cache renders fuller content before the timeline attaches.
🔎 The Problem
.reveal {
animation: fade-in linear;
animation-timeline: scroll();
animation-range: entry 0% cover 40%;
}
/* Works on first (cold-cache) load. On a warm-cache reload, images
above .reveal finish loading before the timeline attaches, the
scrollable height is already final, and .reveal appears to have
skipped straight to its end state. */
✅ Fix: Stop the Scroller’s Size From Changing After the Timeline Attaches
- Reserve layout space for dynamically-loaded content (fixed dimensions,
aspect-ratioboxes) so the scrollable height doesn’t change after the timeline attaches, instead of letting layout shift happen afterward. - For content that must load asynchronously, delay attaching
animation-timelineto the affected elements until that content has settled, by toggling the timeline-bearing class only once a load/render signal fires. - Test the animation against both a cold cache and a warm cache, since a warm cache loading content faster and more completely before the timeline attaches is exactly the condition that exposes this gap.
🚨 Why This Is Dangerous
- An animation that looks correct in every manual test — where you watch it attach cleanly — but silently breaks for users with a faster connection or a warm cache can go unnoticed in review and ship broken to exactly the visitors with the best browsing conditions.
A scroll-driven timeline measures the scroller once, at the moment it attaches — grow the content after that moment, and the timeline keeps grading against a page that no longer exists.
