--- name: gsap description: | GSAP (GreenSock Animation Platform) — high-performance JavaScript animation engine with a plugin ecosystem. Covers tweens, easing, timelines, ScrollTrigger and the useGSAP React hook. USE WHEN: user mentions "GSAP", "GreenSock", "ScrollTrigger", "useGSAP", "timeline animation", "tween", asks about scroll-driven sequences or complex animation choreography DO NOT USE FOR: React-idiomatic declarative animation (use `framer-motion`), SVG path morphing basics (use `svg-animation`), 3D scenes (use `three-js`) allowed-tools: Read, Grep, Glob, Write, Edit --- # GSAP Skill GreenSock Animation Platform — high-performance JS animation engine with plugin ecosystem. ## Install ```bash npm install gsap # Plugins (ScrollTrigger free, others require club membership): # ScrollTrigger, Flip, Observer, ScrollSmoother — included in gsap package ``` ## Core API ```ts import gsap from "gsap"; import { ScrollTrigger } from "gsap/ScrollTrigger"; import { Flip } from "gsap/Flip"; gsap.registerPlugin(ScrollTrigger, Flip); ``` | Method | Purpose | |--------|---------| | `gsap.to(target, vars)` | Animate FROM current state TO vars | | `gsap.from(target, vars)` | Animate FROM vars TO current state | | `gsap.fromTo(target, from, to)` | Explicit start and end | | `gsap.set(target, vars)` | Instant set, no animation | | `gsap.timeline(vars)` | Sequence multiple tweens | | `gsap.context(fn, scope)` | Scope cleanup (React) | | `gsap.matchMedia()` | Responsive animations | ## Tween Properties ```ts gsap.to(".box", { x: 100, // translateX (px) y: -50, // translateY rotation: 360, // degrees scale: 1.5, opacity: 0, duration: 1, delay: 0.2, ease: "power2.out", stagger: 0.1, // when targeting multiple elements repeat: -1, // -1 = infinite yoyo: true, // reverse on repeat onComplete: () => console.log("done"), }); ``` ## Easing Reference | Ease | Character | |------|-----------| | `power1-4.in/out/inOut` | Polynomial — power2.out is the go-to | | `elastic.out(1, 0.3)` | Springy bounce | | `back.out(1.7)` | Slight overshoot | | `bounce.out` | Ball bounce | | `circ.out` | Circular — sharp deceleration | | `expo.out` | Dramatic fast-to-slow | | `none` / `linear` | Constant speed | ## Timeline ```ts const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.5 } }); tl.from(".hero-title", { opacity: 0, y: 60 }) .from(".hero-subtitle", { opacity: 0, y: 40 }, "-=0.3") // 0.3s overlap .from(".hero-cta", { opacity: 0, scale: 0.9 }, "+=0.1") // 0.1s gap .from(".hero-image", { opacity: 0, x: 60 }, "<0.2"); // same start as prev + 0.2 // Position parameter: // "<" = same start as previous // ">" = end of previous // "+=n" = n seconds after end // "-=n" = n seconds before end // "1.5" = absolute time in timeline ``` ## ScrollTrigger ```ts gsap.to(".panel", { xPercent: -100 * (panels.length - 1), ease: "none", scrollTrigger: { trigger: ".scroll-container", pin: true, // pins the trigger element during scroll scrub: 1, // smooth scrubbing (lag in seconds) snap: 1 / (panels.length - 1), end: () => `+=${containerRef.current?.offsetWidth}`, } }); // Callbacks ScrollTrigger.create({ trigger: "#section", start: "top 80%", end: "bottom 20%", onEnter: () => console.log("entered"), onLeave: () => console.log("left"), onEnterBack: () => console.log("entered back"), markers: process.env.NODE_ENV === "development", // visual debug markers }); ``` ## React Integration — useGSAP hook ```tsx import { useGSAP } from "@gsap/react"; import gsap from "gsap"; import { useRef } from "react"; gsap.registerPlugin(useGSAP); function AnimatedHero() { const containerRef = useRef(null); useGSAP(() => { // All GSAP code here is automatically cleaned up on unmount gsap.from(".title", { opacity: 0, y: 60, duration: 0.8, ease: "power3.out" }); }, { scope: containerRef }); // scope = only select within containerRef return (

Hello

); } ``` ## Context (manual cleanup without useGSAP) ```tsx useEffect(() => { const ctx = gsap.context(() => { gsap.from(".item", { opacity: 0, stagger: 0.1 }); }, containerRef); return () => ctx.revert(); // kills all tweens created in context }, []); ``` ## Stagger ```ts gsap.from(".card", { opacity: 0, y: 30, stagger: { amount: 0.6, // total time spread across all elements from: "center", // start: "start" | "end" | "center" | "random" | index ease: "power2.inOut", grid: [3, 4], // for grid layouts } }); ``` ## SVG Path Draw (manual, no plugin) ```ts function animatePath(el: SVGPathElement) { const len = el.getTotalLength(); gsap.set(el, { strokeDasharray: len, strokeDashoffset: len }); gsap.to(el, { strokeDashoffset: 0, duration: 2, ease: "power2.inOut" }); } ``` ## matchMedia (responsive) ```ts const mm = gsap.matchMedia(); mm.add("(min-width: 768px)", () => { gsap.from(".title", { x: -100, opacity: 0 }); }); mm.add("(max-width: 767px)", () => { gsap.from(".title", { y: 40, opacity: 0 }); }); // Cleanup: return () => mm.revert(); ``` ## Reduced Motion ```ts const prefersReduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches; gsap.to(".element", { x: prefersReduced ? 0 : 200, duration: prefersReduced ? 0 : 1, opacity: 1, }); ``` ## Pitfalls - Always `ctx.revert()` or use `useGSAP` in React — GSAP tweens survive component unmount otherwise - `scrub: true` = hard sync with scroll; `scrub: 1` = 1s lag (smoother) - `pin: true` — the trigger element must have explicit height for the pinned section to work - Avoid `document.querySelector` inside components — use refs with `gsap.context(scope)` - `ScrollTrigger.refresh()` after dynamic content loads (images, fonts)