Skip to content

OneWave-AI/open-agent-stack / plugins/vibe-stack/skills/gsap-web

gsap-web

Unverified

GSAP 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

  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.

  4. ScrollTrigger, carefully. Attach the trigger to the animation, not the other way around, and let useGSAP clean 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.

  5. Verify the teardown. Navigate away and back twice. Animations should not stack, ScrollTriggers should not multiply (ScrollTrigger.getAll().length stays flat), and nothing should throw about a null element. If any of those fail, something was created outside useGSAP's scope.

Rules

  • Animate x/y/scale/rotation/opacity. GSAP's x/y compile to transform -- animating top/left instead costs layout on every frame.

  • Never animate in a useEffect without cleanup. useGSAP exists precisely so you do not have to remember ctx.revert().

  • Set will-change through GSAP's own force3D behavior or not at all; a permanent will-change: transform on many elements is a memory cost, not a speedup.

  • Kill markers: true before 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.

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: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall