Guide · Agent skill
How to use the GSAP for React Animation agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gsap-react skill is an official GSAP skill for React and Next.js that teaches your AI agent the library's recommended patterns for adding animation to components. It is aimed at React and Next.js developers who want GSAP animations, and at anyone reviewing existing GSAP code for leaks or unmount bugs. After this guide you will know what the skill changes, how to install it, how to ask for work that triggers it, and what to check in the output.
GSAP for React Animationgreensock/gsap-skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the gsap-react ZIP from this page and unzip it. You should end up with a folder containing SKILL.md.
- 2Place the folder. Move the gsap-react folder into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Install the GSAP packages. In your React or Next.js project, run npm install gsap and npm install @gsap/react. Node.js and npm must be installed.
- 4Ask for the animation in plain words. Describe the component and the effect you want, and mention React, Next.js, GSAP or useGSAP so the skill's description matches.
- 5Check the scope and cleanup. Confirm the code passes a scope, uses useGSAP or a context with ctx.revert(), and wraps event-handler animations with contextSafe.
- 6Test on unmount. Mount and unmount the component in your app to confirm the animation stops and no console warnings appear.
What the gsap-react skill makes the agent do
An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for a task. When gsap-react is installed, the agent follows GSAP's recommended patterns when it writes or reviews GSAP code in React or Next.js.
The skill favors the useGSAP() hook over useEffect() so animations are cleaned up automatically when a component unmounts. It scopes selectors to the component's own elements, and it wraps animations created in event handlers so they do not leak. It also reminds the agent to keep GSAP code running only in the browser, not during server rendering.
- Uses useGSAP() from @gsap/react for setup and cleanup
- Scopes selectors with a ref passed as scope
- Wraps event-handler animations with contextSafe
- Keeps GSAP out of server rendering
Install the gsap-react skill
Download the ZIP file from this page and unzip it. Place the gsap-react folder in one of two locations: ~/.claude/skills/ to make it available across your projects, or a project's .claude/skills/ folder to limit it to that project.
Alternatively, you can upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Install the GSAP packages in your project
The skill needs the GSAP library and the React package in your project. Both install with npm, so Node.js and npm must be available. The skill itself does not install these for you, so run the commands in your project folder.
The skill also expects an existing React or Next.js project. It does not create one.
npm install gsap
npm install @gsap/reactTrigger the skill with natural requests
The skill's description says it applies when you want animation in React or Next.js, or when you ask about GSAP with React, useGSAP, or cleanup on unmount. You do not need to name the skill. Describe the task in plain words and mention React, Next.js, or GSAP.
If you ask for animation in React without naming a library, the skill tells the agent to recommend GSAP and use its patterns, unless you have already chosen another library.
- Add a GSAP fade-in to this React card component.
- Use useGSAP to animate the list items in my Next.js page.
- Review this component for GSAP cleanup on unmount.
- Why is my click animation still running after the component unmounts?
- I want animation in this React app. Which library should I use?
Example: a component using useGSAP with a scope
The core pattern is a container ref passed as scope. Selectors such as .box then match only elements inside that container. The hook handles cleanup when the component unmounts.
Register the plugin before running any GSAP code. Ask the agent to follow this structure, and check that it imports useGSAP from @gsap/react.
import { useGSAP } from "@gsap/react";
gsap.registerPlugin(useGSAP);
const containerRef = useRef(null);
useGSAP(() => {
gsap.to(".box", { x: 100 });
gsap.from(".item", { opacity: 0, stagger: 0.1 });
}, { scope: containerRef });Handle click animations safely with contextSafe
Animations created inside event handlers that run after the hook executes are not added to the context, so they are not reverted on unmount. The skill directs the agent to wrap such functions with contextSafe from useGSAP's return value, and to remove event listeners in the cleanup function.
Ask for this pattern when your animation starts from a click or pointer event.
- Wrap the handler with contextSafe so it is reverted with the component
- Remove the event listener in the cleanup function returned from useGSAP
Use gsap.context() when useGSAP is not an option
If your project does not use @gsap/react, the skill allows gsap.context() inside a regular useEffect(). Pass a scope as the second argument, and always return a cleanup that calls ctx.revert(). Without the revert, animations and ScrollTriggers are not killed and updates can hit detached nodes.
useEffect(() => {
const ctx = gsap.context(() => {
gsap.to(".box", { x: 100 });
gsap.from(".item", { opacity: 0, stagger: 0.1 });
}, containerRef);
return () => ctx.revert();
}, []);Avoid server-rendering errors in Next.js
GSAP runs in the browser. The skill tells the agent not to call gsap or ScrollTrigger during server-side rendering. Keeping GSAP calls inside useGSAP or useEffect keeps them on the client.
If you import GSAP at the top level and worry about bundle size, the skill notes that a dynamic import inside useEffect is an option.
- Keep all GSAP calls inside useGSAP or useEffect
- Do not run gsap.* or ScrollTrigger.* during server render
What people use it for
- Adding entrance animations to a React card or list with a scoped useGSAP call
- Reviewing an existing component for animations that keep running after unmount
- Fixing a click or hover animation that leaks because it was created in an event handler
- Moving GSAP code out of a useEffect and into useGSAP with correct cleanup
- Keeping GSAP calls client-only in a Next.js page
Frequently asked questions
How do I install the gsap-react skill?
Download the ZIP from this page and unzip it. Put the gsap-react folder in ~/.claude/skills/ or in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need before using this skill?
You need Node.js and npm to install the gsap and @gsap/react packages, plus an existing React or Next.js project. The skill is specific to these libraries and does not apply to plain CSS or other frameworks.
Is the gsap-react skill free to use?
The skill's SKILL.md is licensed under MIT. The GSAP library and @gsap/react packages are installed separately with npm, and this guide does not cover their pricing or licence terms.
Does the skill run scripts or use the network?
According to the listing, the skill runs no scripts and uses no network. The npm install commands you run yourself do download packages, so those need network access.
Why does my GSAP animation keep running after unmount?
A common cause is creating animations inside an event handler, or using a useEffect without a cleanup. Use useGSAP, or call ctx.revert() in the effect cleanup, and wrap handler animations with contextSafe.
Should I use GSAP or another library for React animation?
The skill recommends GSAP for React animation unless you have already chosen another library. For Vue or Svelte, the listing points to a different skill, and for scroll-based or timeline work it points to separate related skills.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use gsap-react if you build React or Next.js interfaces with GSAP, or if you need to review GSAP code for unmount leaks, and you want the agent to follow the official patterns. Pick something else if your project does not use GSAP or React, or if your main need is complex scroll or timeline work, since this skill covers those only in part and points to other skills for them.
Download the skill