This portfolio uses GSAP for all its animations: titles rising letter by letter, a map of Normandy drawing itself on scroll, text lighting up word by word. Here's what the redesign taught me, especially about what goes wrong when you mix animation and server rendering.
Start in the right place
GSAP manipulates the DOM, so nothing should run on the server. In Nuxt, everything starts in onMounted, and everything must be cleaned up when leaving the page, or ScrollTrigger instances pile up on every navigation.
gsap.matchMedia() solves both problems, and handles accessibility and responsive behaviour too:
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
const root = ref<HTMLElement>()
let media: gsap.MatchMedia | undefined
onMounted(() => {
gsap.registerPlugin(ScrollTrigger)
media = gsap.matchMedia()
media.add('(prefers-reduced-motion: no-preference)', () => {
const q = gsap.utils.selector(root.value)
gsap.from(q('.title'), { y: 24, opacity: 0, duration: 0.8 })
}, root.value)
})
onBeforeUnmount(() => media?.revert())
Everything created in the callback is undone by revert(). And people who asked their device to reduce motion simply see the page, with nothing more to code.
The flash on load
It's the first problem you run into. The server sends the full page, the browser displays it, then the JavaScript arrives and gsap.from() puts elements back to their starting state. The result: the title appears, disappears, then animates.
The fix is to hide it with CSS until the animation starts. But careful: if the script never loads, your title stays invisible forever. So you need a safety net:
@media (prefers-reduced-motion: no-preference) {
.hero:not(.hero-ready) .hero-in {
opacity: 0;
animation: hero-fallback 0.3s 2.5s forwards;
}
}
@keyframes hero-fallback {
to { opacity: 1; }
}
The script adds hero-ready right before starting the animation. If it never runs, the content still appears after 2.5 seconds. The text stays in the HTML, so search engines can read it.
Keep the trade-off in mind: a title hidden until JavaScript runs takes longer to appear on slow connections, which can hurt LCP. Reserve this for what deserves it, and watch your production metrics.
GSAP's lazy rendering
A detail I learned the hard way: by default, GSAP applies starting values on the next render cycle. For an entrance, I prefer applying them right away with lazy: false, to rule out any frame shown in the final state:
gsap.timeline({ defaults: { ease: 'expo.out', lazy: false } })
Sticky rather than pin
To hold a section during scroll, the reflex is pin: true. It works, but GSAP wraps the section and switches it to position: fixed, which can break with some parents.
CSS already does this. The section keeps its natural behaviour, and ScrollTrigger only drives the animation:
<div class="track" style="height: 260vh">
<div class="sticky top-0 h-screen">
<!-- the held content -->
</div>
</div>
One trap to know: a transform on a parent can interfere with these positions, including a simple entrance animation on a container. And overflow: hidden on a parent breaks sticky, whereas overflow-x: clip doesn't.
Splitting text without losing it
SplitText, now free, splits a title into letters and can create the mask needed to make them rise:
const title = SplitText.create(el, { type: 'words,chars', mask: 'chars' })
gsap.from(title.chars, { yPercent: 110, stagger: 0.03 })
Two surprises:
- Words break anywhere. Once split into letters, a hyphenated title can wrap mid-word.
type: 'words,chars'helps, andwhite-space: nowrapsolves it for short titles. - Gradient text breaks.
background-clip: textdoesn't survive letters being transformed separately. For those titles, I animate the whole block with aclip-pathinstead of letter by letter.
Drawing a map on scroll
The classic technique for tracing an SVG uses pathLength="1" and stroke-dashoffset. It stops working if you add vector-effect: non-scaling-stroke: dashes are then computed in screen space, and your line shows up dotted. To keep a constant thickness during a zoom, compute stroke-width from the zoom level instead.
Test for real
One last lesson. A background browser doesn't fire requestAnimationFrame, so GSAP doesn't advance there: your measurements are wrong, and an animation can look stuck when it works fine. Also check the page width after each effect: an element leaving the screen during a zoom easily creates horizontal scrolling, invisible as long as you only look at the start of the animation.
In short
- Centralise everything in
gsap.matchMedia()for cleanup and accessibility. - Hide little, and always with a no-JavaScript fallback.
- Prefer
stickytopinwhen you can. - Measure in production: a beautiful animation isn't worth a slow site.
Animation should serve reading. The ones I kept here are those that guide the eye, and I removed several along the way because they added nothing.