Scroll Reveal Choreography

When to use this

• Animating elements into view as the user scrolls down a page.
• Setting up IntersectionObserver with precise thresholds and margins for reveal timing.
• Deciding between once-only reveals and repeat-on-re-enter reveals.
• Avoiding the universal "everything fades up 20px" pattern that reads as AI-generated.
• Do NOT use this for scroll-linked/scrubbed animations (parallax, progress bars); see gsap-scrolltrigger or css-scroll-driven-animations instead.

Mental model

Scroll reveal is fundamentally about timing the moment an element becomes "noticed." IntersectionObserver fires when an element crosses a visibility threshold relative to the viewport (or a scrollable ancestor). The callback tells you "this element is now X% visible." You toggle a class or trigger an animation in response.

The key insight most implementations miss: the reveal should fire BEFORE the element is fully in view, not after. If you wait until the element is 50% visible, the user has already been looking at a blank space for several hundred pixels of scroll. The element should start animating when it is about to enter, not when it has arrived.

This is controlled by rootMargin. A rootMargin: "0px 0px -80px 0px" fires the callback when the element is 80px inside the bottom edge of the viewport, meaning it triggers before the user has scrolled the element fully into view. Negative bottom margin is the most important tuning parameter. Positive bottom margin (firing before the element enters the viewport at all) usually looks wrong because the animation completes before the user sees it.

threshold controls what percentage of the element must be visible. For reveal animations, threshold: 0 (any pixel visible) combined with the right rootMargin is almost always correct. Higher thresholds cause reveals to fire late on tall elements.

The "once vs repeat" decision: most scroll reveals should fire once. Repeating the animation on every scroll up/down makes the page feel fidgety and performant concerns arise from re-creating animations. The exception is small decorative elements (dividers, counters) where replay adds value.