OneWave-AI/open-agent-stack / plugins/vibe-stack/skills/gsap-web
gsap-web
UnverifiedGSAP in a React or Next.js app without the leaks -- timelines over stacked tweens, useGSAP and context for cleanup, ScrollTrigger set up so it survives route changes and layout shifts. Use when building GSAP animations in a component-based app.
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
-
Scope everything.
useGSAPwith 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
.cardcannot reach into another component's markup. -
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 previousUse labels (
tl.addLabel('reveal')) once a timeline passes about five steps. -
fromvsfromTo.fromanimates to the element's current CSS, which is fragile when other code or a re-render changes that state -- an interruptedfromcan leave the element stuck at its start values. For anything that can be interrupted or replayed, usefromToand state both ends explicitly. AddimmediateRender: falsewhen afrominside a timeline flashes its end state on load. -
ScrollTrigger, carefully. Attach the trigger to the animation, not the other way around, and let
useGSAPclean it up:gsap.to('.panel', { y: -80, scrollTrigger: { trigger: '.panel', start: 'top 80%', end: 'bottom 20%', scrub: 1, // number = smoothing lag in seconds // markers: true, // dev only -- never commit this }, })After images, fonts, or async content land, call
ScrollTrigger.refresh()-- stale start/end positions are the number-one ScrollTrigger bug. In Next.js, refresh on route change too. -
Verify the teardown. Navigate away and back twice. Animations should not stack, ScrollTriggers should not multiply (
ScrollTrigger.getAll().lengthstays flat), and nothing should throw about a null element. If any of those fail, something was created outsideuseGSAP's scope.
Rules
-
Animate
x/y/scale/rotation/opacity. GSAP'sx/ycompile totransform-- animatingtop/leftinstead costs layout on every frame. -
Never animate in a
useEffectwithout cleanup.useGSAPexists precisely so you do not have to rememberctx.revert(). -
Set
will-changethrough GSAP's ownforce3Dbehavior or not at all; a permanentwill-change: transformon many elements is a memory cost, not a speedup. -
Kill
markers: truebefore committing. It ships to production more often than you would think. -
Respect reduced motion at the source with
gsap.matchMedia(), so the reduced branch is a real alternative timeline rather than a disabled one:const mm = gsap.matchMedia() mm.add('(prefers-reduced-motion: no-preference)', () => { /* full timeline */ }) mm.add('(prefers-reduced-motion: reduce)', () => { /* fades only */ }) -
Do not reach for GSAP when CSS suffices. A hover state, a fade-in, a spinner -- those are transitions and keyframes. GSAP earns its bundle on sequenced timelines, scroll scrubbing, and anything needing runtime control.
-
GSAP's ScrollSmoother, SplitText, and other formerly-paid plugins are free as of GSAP 3.13, but every plugin is bundle weight -- add one only when the effect is core to the page.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |