gsap-react

Overview of gsap-react skill

What gsap-react is for

gsap-react is the official GSAP skill for React and React-based frameworks like Next.js. It helps you build animations with the right React-safe patterns: useGSAP(), scoped selectors, gsap.context(), and automatic cleanup. Use the gsap-react skill when you need to add motion in a component without fighting re-renders, unmounts, or DOM-selection bugs.

Who should use it

This skill fits frontend engineers who already know React and want reliable animation setup, not a generic animation primer. It is especially useful when you are deciding whether to use GSAP in a React app, when an animation breaks after route changes, or when you need guidance on the gsap-react install and integration flow.

What makes it different

The main value is React-specific safety. Instead of writing a plain useEffect() animation and manually cleaning up, gsap-react guides you toward useGSAP() and scoped targets so animations stay predictable. It also helps prevent the common mistakes that block adoption: unscoped selectors, missing plugin registration, and SSR-related confusion.

How to Use gsap-react skill

Install GSAP and the React package

For gsap-react install, add both packages to your app:

npm install gsap
npm install @gsap/react

Then register the plugin before using useGSAP() or other GSAP code:

import { useGSAP } from "@gsap/react";
gsap.registerPlugin(useGSAP);

If you skip registration, the hook will not behave as expected.

Turn a rough goal into a usable prompt

The best gsap-react usage starts with a concrete animation goal, not “make it look better.” Include: the component type, what should animate, when it should start, whether it should repeat, and whether the effect must survive route changes or cleanup on unmount.

A strong prompt looks like:

• “Animate three cards sliding in on mount in a Next.js client component, scoped to this container.”
• “Convert this useEffect() GSAP animation to useGSAP() with cleanup and refs.”
• “Add hover and scroll-triggered motion, but keep selectors scoped to the component.”

Read the right files first

Start with SKILL.md, then inspect the parts that define behavior and constraints in the repo copy. In this skill, the useful path is short, so read the core instructions first and then any linked examples or surrounding docs if present. For gsap-react, the main decision points are the When to Use This Skill, Installation, and Prefer the useGSAP() Hook sections.

Use the React-safe workflow

The default workflow is: import useGSAP, register the plugin, create a ref, scope selectors to that ref, and put animation code inside the hook. Prefer this over direct document-wide selectors or unscoped timelines. If you need callbacks that fire later, use contextSafe so delayed interactions still clean up correctly.

gsap-react skill FAQ

Do I need gsap-react for every GSAP animation in React?

No. If the animation is small and already solved in another part of your stack, the skill may be unnecessary. Use gsap-react when the code touches component lifecycle, cleanup, scoped DOM targeting, or framework-specific behavior in React or Next.js.

How is this different from an ordinary prompt?

A normal prompt may produce working animation code, but gsap-react adds opinionated React integration rules that matter in production: plugin registration, useGSAP(), scoped selectors, and cleanup behavior. That reduces debugging time and makes the output more reusable in real app code.

Is gsap-react beginner-friendly?

Yes, if the user can describe a component and a desired motion. It is not a beginner course on animation theory; it is a practical gsap-react guide for getting from a rough UI idea to safe React code. Beginners get the best results when they provide the component structure and expected trigger.

When should I not use it?

Do not choose gsap-react for non-React frameworks, or when you need a library-agnostic animation answer. For Vue, Svelte, and other stacks, use the framework-specific GSAP skill instead. If you only need core tween or timeline syntax, another GSAP skill may be a better fit.

How to Improve gsap-react skill

Give structure, not just intent

The best improvement to gsap-react output is specificity. Provide the component markup, the selectors or refs you already have, and the exact trigger conditions. “Animate the hero” is weak; “fade in the title, slide the CTA, and stagger the feature cards on first render” gives the skill enough detail to produce usable code.

Mention the constraints that change the implementation

Call out SSR, route transitions, reduced motion, and cleanup expectations early. These constraints decide whether the answer should use useGSAP(), a client component, scoped refs, or a different animation approach. If your app is Next.js, say so explicitly in the prompt.

Review the first result for scoping mistakes

Common failure modes are unscoped selectors, animations that run too early, and code that ignores component unmount. If the first output uses broad selectors like .box without a scope, ask for a ref-scoped rewrite. If callbacks trigger later, request contextSafe handling in the follow-up.

Iterate with the exact motion you want

After the first pass, refine by changing one variable at a time: timing, easing, stagger, trigger, or cleanup behavior. A good gsap-react usage loop is: implement the base animation, test it in the component, then ask for targeted adjustments like “make it less aggressive on mobile” or “move the trigger to hover only.”