What is the gsap-react skill?
gsap-react is an official SKILL.md in the greensock/gsap-skills repository. It teaches an AI coding agent GSAP in React and Next.js: the useGSAP hook, refs and scope, dependency handling, gsap.context fallback, contextSafe callbacks and keeping GSAP off the server render.
gsap-react is the React skill in the official greensock/gsap-skills set. Its SKILL.md applies when someone wants GSAP animation in React or Next.js, or asks about useGSAP, refs or cleanup on unmount. It recommends GSAP for React animation unless another library is named.
Tweens come from gsap-core, scroll from gsap-scrolltrigger, and Vue and Svelte from gsap-frameworks.
What changes in your agent's output
- GSAP setup lives in
useGSAP()from the@gsap/reactpackage instead of a bareuseEffect(). - Selectors are scoped with a ref, so
.boxonly matches elements inside the component. - Cleanup is automatic on unmount, and callbacks that fire later are wrapped with
contextSafe. - Where the hook is not available, the agent uses
gsap.context()in an effect and returnsctx.revert(). - No GSAP or ScrollTrigger call runs during server render.
Dependencies and revertOnUpdate
By default useGSAP() uses an empty dependency array, so it does not run on every render. The second argument takes either a dependency array or a config object with dependencies, scope and revertOnUpdate.
revertOnUpdate: true reverts the context and runs cleanup every time a dependency changes. That is the option for animations driven by changing props or state.
Who the gsap-react skill is for
Best for
- React and Next.js apps where animation leaks, doubles on re-render or crashes in server render.
- Agents that target elements by bare selector strings that can match outside the component.
- Teams pairing it with vercel-react-best-practices for wider React guidance.
Not for
- Vue, Nuxt or Svelte, which gsap-frameworks covers.
- Plain HTML pages with no component lifecycle.
How to install GSAP React Skill: useGSAP, Scope and Cleanup
git clone https://github.com/greensock/gsap-skills.git/plugin marketplace add greensock/gsap-skills, which the README documents.Clone the repository
Run
git clone https://github.com/greensock/gsap-skills.git. The skill is the skills/gsap-react folder, which holds one SKILL.md.Copy the skill folder
Copy skills/gsap-react into your agent's skills directory. The README lists ~/.claude/skills/ for Claude Code, ~/.cursor/skills/ for Cursor, ~/.config/opencode/skills/ for OpenCode and ~/.codex/skills/ for OpenAI Codex.
Install GSAP in the project
The skill guides the agent's code but does not add the library. Add the gsap package to your project with your package manager. It includes every plugin.
Add the React package
Also add the
@gsap/reactpackage with your package manager, then registeruseGSAPwithgsap.registerPlugin()once before using it.Ask for animation work
Describe the motion you want, such as a staggered card entrance, and name the skill if your agent needs a nudge.
Check that it loaded
Ask the agent to animate a card list on mount in a React component. The result should use useGSAP() with a scope ref and no unscoped selectors.
Key features
- useGSAP hookUse
useGSAP()from@gsap/reactrather thanuseEffect()oruseLayoutEffect(). It handles cleanup and gives scope andcontextSafe. - Install both packagesThe skill's install section lists the gsap library and the
@gsap/reactpackage. RegisteruseGSAPas a plugin before use. - ScopePass a ref or element as
scopeso selectors such as.boxonly match inside that root. Unscoped selectors are on the Do Not list. - Refs for targetsUse refs to point at the elements being animated, and animate them from inside the hook callback.
- Dependency array and revertOnUpdatePass
dependenciesandrevertOnUpdate: trueto re-run and revert the animation when values change. - gsap.context fallbackWhen
useGSAPis not an option, creategsap.context()in an effect with a scope and always return a cleanup that callsctx.revert(). - contextSafe callbacksWrap handlers such as click callbacks with
contextSafeso they do nothing after unmount and avoid React warnings. - Server-side renderingKeep all GSAP and ScrollTrigger code in client-only lifecycle. Dynamic import inside an effect is an option for bundle size.
- Automatic cleanupAnimations and ScrollTriggers are reverted on unmount, so nothing runs on detached nodes.
Frequently asked questions
What is the gsap-react skill?
It is the skills/gsap-react folder in the greensock/gsap-skills repository. Its SKILL.md teaches an AI coding agent how to use GSAP in React and Next.js with useGSAP, refs, scope, contextSafe, gsap.context fallback and server-render safety.
How do I install gsap-react?
Clone greensock/gsap-skills and copy skills/gsap-react into your agent's skills folder. The README lists paths for Claude Code, Cursor, OpenCode and OpenAI Codex. Add the gsap and @gsap/react packages to your project, because the skill only guides code.
Why use useGSAP instead of useEffect?
The skill says useGSAP handles cleanup automatically and provides scope and contextSafe. With a plain effect you must remember to revert animations yourself, or tweens and ScrollTriggers keep running on stale elements.
What does scope do?
It limits selector matching to a root ref or element, so a class like .box only affects elements inside the component. The skill lists unscoped selectors as a mistake because they can hit elements elsewhere on the page.
Does it work with Next.js?
Yes. The skill has a server-side rendering section that says GSAP and ScrollTrigger must only run on the client. It suggests useGSAP or useEffect and notes that a dynamic import in an effect is an option for bundle size.
What is contextSafe for?
It wraps callbacks that fire later, such as onComplete or click handlers, so they become no-ops after the component unmounts. The skill says this avoids React warnings and keeps late callbacks from touching nodes that are gone.
Does gsap-react include ScrollTrigger rules?
Only the React-specific part, which is cleanup through useGSAP or gsap.context, since useGSAP reverts ScrollTriggers on unmount. The trigger configuration lives in gsap-scrolltrigger, and sequencing lives in gsap-timeline, so each skill stays short.