gsap-web

GSAP for Web Apps

GSAP is straightforward until it meets React. Then every animation that worked in a CodePen starts double-firing in Strict Mode, surviving unmount, and pointing at stale DOM after a route change. The library is not the problem -- lifecycle is. These are the patterns that hold up.

Setup

Install gsap and @gsap/react. Register plugins once, at module scope in a client component, never inside render:

'use client'
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
import { useGSAP } from '@gsap/react'

gsap.registerPlugin(ScrollTrigger, useGSAP)
gsap.defaults({ duration: 0.28, ease: 'power3.out' })  // from motion-system

In Next.js App Router, anything touching GSAP is a client component. GSAP reads the DOM, so it cannot run during SSR -- a window is not defined build error means the import climbed into a server component.

Workflow

1. Scope everything. useGSAP with a container ref. It reverts every animation created inside on unmount and handles Strict Mode's double-invoke, which is the source of nearly every "it fires twice" report.

   const container = useRef(null)
   useGSAP(() => {
     gsap.from('.card', { y: 24, opacity: 0, stagger: 0.05 })
   }, { scope: container })
   

   Selector strings inside the callback resolve within the scope, so .card cannot reach into another component's markup.

2. Timelines, not stacked tweens. Three sequenced tweens with hand-computed delays become unmaintainable the moment one duration changes. One timeline with the position parameter stays readable:

   const tl = gsap.timeline()
   tl.from('.title', { y: 30, opacity: 0 })
     .from('.sub',   { y: 20, opacity: 0 }, '-=0.15')   // overlap
     .from('.cta',   { scale: 0.96, opacity: 0 }, '<')  // with previous
   

   Use labels (tl.addLabel('reveal')) once a timeline passes about five steps.

3. from vs fromTo. from animates to the element's current CSS, which is fragile when other code or a re-render changes that state -- an interrupted from can leave the element stuck at its start values. For anything that can be interrupted or replayed, use fromTo and state both ends explicitly. Add immediateRender: false when a from inside a timeline flashes its end state on load.