GSAP motion architecture
Verified baseline (2026-11-15)
[email protected]is the latest on npm. Its licence field is "Standard 'no charge' license" (gsap.com/standard-license): free for commercial sites, including client work. The one Prohibited Use is building no-code visual animation builder tools that compete with Webflow. All plugins ship in the public package: ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools, and more.@gsap/[email protected]providesuseGSAP.- Re-check before a new project:
npm view gsap version licenseandls node_modules/gsap/*.js. - Use ScrollSmoother or Lenis, never both. This studio standardises on Lenis (
lenis-scrollskill).
Architecture (copy assets/ into src/motion/)
| File | Role |
|---|---|
assets/registry.ts | Registers plugins once, creates the project's CustomEases, sets defaults, ScrollTrigger.config({ ignoreMobileResize: true }). Everything imports gsap from here. |
assets/tokens.ts | Motion tokens (durations, eases, staggers) mirrored from ANIMATION_SPECIFICATION.md + prefersReducedMotion() |
assets/lit.ts | Example reusable text primitive: SplitText with aria:'auto', autoSplit, and onSplit returning the tween. Adapt the reveal to the brand (lit, masked, slid…). |
assets/useReducedMotion.ts | Live prefers-reduced-motion hook for DOM-level switches (e.g. render static steps instead of a pin) |
assets/examples/*.tsx | Tested patterns from the reference demo: pinned scrubbed sequence (Method), Flip filter (ScheduleIndex), quickTo-driven interactive (TheHour), once-reveals (Rooms), route transition veil (Router) |
These files are the verified implementation from demo/ in this repo, exercised by its Playwright suite (cleanup across routes, reduced motion, scroll sync).
Rules that prevent 90% of GSAP bugs in React
- Every animation lives inside
useGSAP(() => {...}, { scope: ref }). The context reverts all tweens, ScrollTriggers, SplitTexts and matchMedia branches on unmount. Event-handler animations usecontextSafe. - Never create ScrollTriggers at module scope or in plain
useEffectwithout reverting them. Never callScrollTrigger.killAll()as a cleanup strategy. - One
gsap.matchMedia()per section withmotion/reduce(and desktop/mobile) conditions. Initial hidden states are set inside the motion branch, so no-JS and reduced-motion users see final content. - Strict Mode safe:
useGSAPhandles React 18/19 double-invocation. Verify with a leak check:ScrollTrigger.getAll().lengthreturns to baseline after navigating away and back. - Refresh after layout changes: after fonts load (
document.fonts.ready.then(() => ScrollTrigger.refresh())), after filtering lists, and after route content mounts.invalidateOnRefresh: trueon any trigger whose values are computed from layout. - Pin correctly: pin an inner wrapper, keep
pinSpacing, give it amin-height: 100svhthat doesn't depend on webfonts, and useanticipatePin: 1with Lenis. Use one pin per experience; stacked pins confuse users. - Animate cheap properties: transform, opacity, clip-path; CSS variables only on small subtrees. Avoid width/height/top/left in scrubbed timelines, and read layout before writing (GSAP batches its own writes).
will-changeonly while animating, and only on a few layers.
Recipes
references/recipes.md has tested or documented patterns for: cinematic hero sequence, SplitText reveals (chars/words/lines, masked), clip-path and mask transitions, pinned scrub storytelling, horizontal scroll section (containerAnimation), parallax layers, Flip state morphs, Observer-driven gesture sections, Draggable + Inertia carousels, magnetic buttons, cursor followers, SVG morph/draw, image distortion handoff to WebGL, page transitions, and 3D scroll with a WebGL camera.
references/react-lifecycle.md covers route changes, resize, content changes and debugging leaks.
Purposeful motion checklist (before you animate)
- What does this animation communicate (hierarchy, causality, state, brand material)? If nothing, delete it.
- Is it the signature moment, or should it stay quiet?
- What does reduced motion show instead? (It must remain fully understandable.)
- What is the mobile expression? (Hover effects need a touch alternative; pins get shorter.)
- How many ScrollTriggers does the page create? Write the inventory into the spec so QA can assert it.