Scroll

invalidateOnRefresh

invalidateOnRefresh is a ScrollTrigger option that tells GSAP to re-read each tween's starting values on every `ScrollTrigger.refresh()`. Without it, ScrollTrigger reuses the cached `from` values - which become stale after a layout shift, font load, or dynamic content change. The classic 'why did my pinned section jump after resize' bug is fixed by toggling this on.

Updated June 2, 2026

Mechanics

How invalidateOnRefresh works

When you create a tween with gsap.from() or gsap.fromTo(), GSAP records the element's current values at tween creation time - those become the 'from' state. ScrollTrigger caches its start/end scroll positions at trigger creation time. After a resize, font load, or dynamic content swap, BOTH caches go stale. ScrollTrigger.refresh() recomputes the start/end positions but does NOT re-read the tween's from-values - unless you opt in with invalidateOnRefresh: true.

script.js

On refresh, ScrollTrigger calls the tween's invalidate() method, which clears the cached values. The next tween playback re-reads them. This is what makes the tween survive a font load (which shifts text baselines) or an image load (which shifts layout below).

When

Use invalidateOnRefresh for

  • Pinned sections that contain content sized by the viewport - resize changes the pin distance
  • Stagger reveals across grids that reflow on resize
  • Text reveals with SplitText - font load changes line breaks, invalidating cached positions
  • Image-heavy layouts where late-loading images shift the document above the trigger
  • Anything where the 'from' values depend on measured layout
Alternatives

Use something else when

  • The tween's from values are constant (y: 60, opacity: 0) and never depend on layout - the option is unnecessary
  • You can rebuild the tween entirely on resize via gsap.matchMedia - cleaner than per-tween invalidation when the breakpoint matters
  • The bug isn't the from-values but the start/end positions - that's ScrollTrigger.refresh() alone, no invalidation needed
In production

Used in these Annnimate components

  • The Parallax component uses invalidateOnRefresh so the per-layer transform endpoints recompute when the section height changes
  • The Multi Flip uses invalidateOnRefresh on the scrub timeline so the per-card scroll positions stay accurate across resizes
  • The Popping Text uses invalidateOnRefresh after SplitText runs - font load can shift line breaks, and the per-character from positions need to follow
  • The Image Dissolve Scroll uses invalidateOnRefresh on the pin timeline so the dissolve start position survives image lazy-load reflow
Used in components

See it running in production

ParallaxElements move at different speeds as you scroll so the page feels layered, slower in the back and faster up front.Multi FlipA stack of cards that fans out from a messy pile into a neat grid as you scroll, each one starting overlapped at a random angle.Popping TextLetters pop into place one by one, scaling up from nothing with a little bounce and a random tilt.Image Dissolve ScrollAn image that breaks apart into random organic patches as you scroll, with a glowing edge along the line where it's dissolving.
FAQ

Common questions

What's the difference between invalidateOnRefresh and ScrollTrigger.refresh()?
ScrollTrigger.refresh() recomputes each trigger's start/end positions against the current layout. invalidateOnRefresh: true tells refresh to ALSO clear the tween's cached from-values. Without it, the trigger's positions update but the tween's starting state stays frozen at the original measurements.
Do I need it when using gsap.to() (not gsap.from())?
Less often. gsap.to() reads the FROM values at playback time (the element's current state), not at creation time, so layout shifts before playback don't matter. gsap.from() and gsap.fromTo() cache at creation, which is when staleness can bite. If your to tween has computed END values (a function ref), then yes - invalidate triggers a re-read.
Does invalidateOnRefresh cause performance issues?
Negligible. refresh() runs on resize (debounced), font load, and explicit calls - not on every scroll tick. The cost is one extra tween invalidation per refresh, which is microseconds. There's no per-frame cost.
When should I rebuild the ScrollTrigger instead of using invalidateOnRefresh?
When the structural shape of the animation changes between breakpoints - e.g. a desktop horizontal scroll becomes a vertical stack on mobile. Then gsap.matchMedia is the right tool: each breakpoint creates its own ScrollTrigger which auto-disposes when the media query stops matching. invalidateOnRefresh is for when the shape stays the same but the measurements change.
Why isn't my pinned section refreshing on font load?
Two reasons. (1) You're missing invalidateOnRefresh: true on the pinned trigger - the start position recomputes but the inner tween's from-values don't. (2) You're not calling refresh() on document.fonts.ready - GSAP doesn't watch font load events. Wire document.fonts.ready.then(() => ScrollTrigger.refresh()) at app boot.
PreviousHorizontal scrollHorizontal scroll is a scroll-driven layout where a full-viewport section is pinned in place and its inner track slides sideways as the user scrolls vertically.NextPinningPinning is a ScrollTrigger feature that locks an element in place while scroll progresses past it.
Related conceptsScrollTriggerPinningScrubgsap.matchMedia()