gsap

name

gsap

description

Use this skill whenever the user wants to animate web content with GSAP (GreenSock Animation Platform). Trigger for any request involving GSAP, tweens, timelines, ScrollTrigger, ScrollSmoother, SplitText, Flip, Draggable, MorphSVG, DrawSVG, MotionPath, Observer, scroll-linked animation, parallax, pinned sections, staggered reveals, text/SVG animation, hover micro- interactions, or page-entrance choreography. Also trigger when the user asks to "animate", "add motion to", or "transition" HTML/React/Vue/Svelte/Webflow content and GSAP is the right tool. Always consult this skill before writing GSAP code so version, plugin registration, and cleanup are correct.

GSAP Animation Skill

GSAP v3 — the most widely used JS animation library. As of v3.13 (April 2025) GSAP is 100% free, including every formerly paid "Club" plugin (SplitText, MorphSVG, DrawSVG, ScrollSmoother, Inertia), even commercially. No premium tier, no login CDN. Pin to 3.13.0+ (latest 3.15.x). Docs: https://gsap.com/docs/v3/

This SKILL.md is a lean router. It contains the essentials to start; for anything beyond a basic tween, open the matching reference file below. The references are deep and self-contained — read the one you need rather than guessing API details.

Reference map — read the file that matches the task

Task	File
Full tween/timeline API, every config var, keyframes, getters/setters, callbacks, effects, quickTo	references/core-api.md
All eases in depth + CustomEase / CustomBounce / CustomWiggle / RoughEase / SlowMo	references/easing.md
Anything scroll-related: ScrollTrigger full API, pinning, snap, containerAnimation, batch, refresh	references/scrolltrigger.md
Smooth scrolling, parallax via markup, ScrollSmoother	references/scrollsmoother-observer.md
Text (SplitText), SVG (DrawSVG/MorphSVG/MotionPath), layout (Flip), drag (Draggable/Inertia), physics, pixi, text typing	references/plugins.md
React/useGSAP, Next.js, Vue, Svelte, Angular, Astro, SSR, cleanup	references/frameworks.md
gsap.utils.*, gsap.config, defaults, registerEffect, quickSetter, matchMedia, ticker	references/utils-config.md
Performance, will-change, GPU, accessibility, prefers-reduced-motion, debugging, common errors	references/performance-accessibility-debugging.md
Copy-paste production patterns (40+ recipes)	references/recipes.md
Master timelines, UI playback control, tweenTo/scrubbers, GSDevTools, workflow & testing	references/advanced-timelines-tooling.md
Full standalone runnable HTML demos (hero, scroll story, horizontal, SVG draw, batch, marquee)	references/complete-examples.md
v2→v3 migration, FAQ, pitfalls, decision guides	references/migration-faq.md

Pick the lightest tool

• One property, no sequencing → a single gsap.to()/gsap.from().
• Several things in order → a gsap.timeline() (prefer over many loose tweens).
• Anything scroll-related → ScrollTrigger (scrub = scroll-linked; toggleActions = fire-on-enter).
• Layout/position change (reorder, expand, route transition) → Flip, not manual from/to.
• Per-char/word/line text → SplitText.
• Inside React/Vue/Svelte/SPA → wrap in useGSAP()/gsap.context() with cleanup.

Install

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.13.0/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.13.0/ScrollTrigger.min.js"></script>
<script>gsap.registerPlugin(ScrollTrigger);</script>

import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger); // register EACH plugin ONCE, at app root

npm install gsap (core + all plugins) and npm install @gsap/react (the useGSAP hook). Forgetting registerPlugin is the #1 bug — the plugin's properties are silently ignored.

Minimum viable API

gsap.to(".box",  { x: 200, rotation: 360, duration: 1, ease: "power2.out" }); // current → these
gsap.from(".box",{ autoAlpha: 0, y: -50, duration: 0.8 });                    // these → current
gsap.fromTo(".box", { autoAlpha:0, scale:.5 }, { autoAlpha:1, scale:1, duration:1 });
gsap.set(".box", { x: 100, autoAlpha: 0 });                                   // instant

const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.8 } });
tl.from(".heading", { y:-30, autoAlpha:0 })
  .from(".btn",     { scale:0.8, autoAlpha:0 }, "-=0.4"); // overlap previous by 0.4s

Use autoAlpha (opacity+visibility) over opacity. Use transform shortcuts (x,y,rotation,scale) not raw CSS transform. Details: references/core-api.md.

Position parameter (3rd timeline arg): omit = end · "<" start of previous · ">" end of previous · "<0.5" 0.5s after previous starts · "-=0.3" overlap · "+=0.3" gap · 2 absolute · "label".

The rules that bite (full list in performance-accessibility-debugging.md)

1. Register each plugin once before use, or its props are ignored silently.
2. Transform shortcuts, not raw CSS transform.
3. Pin a real version (3.13.0+) so all plugins are free; never reference a Club/login CDN.
4. Clean up in frameworks/SPAs via useGSAP() or gsap.context().revert().
5. Multiple from() on one element flickers — set immediateRender:false on later ones, or use fromTo.
6. overwrite:"auto" on tweens that can re-fire (hover in/out).
7. Remove markers:true before shipping.
8. Prefer timelines for anything sequenced.
9. Respect prefers-reduced-motion (gate motion behind matchMedia).