/gsap-animation

Table of Contents

1. [Installation & TypeScript Setup](#installation--typescript-setup) 2. [Core Concepts](#core-concepts) 3. [Tweens](#tweens) 4. [Timelines](#timelines) 5. [Easing](#easing) 6. [Staggers](#staggers) 7. [Control Methods](#control-methods) 8. [Utility Methods](#utility-methods) 9. [Context & Cleanup](#context--cleanup) 10. [Responsive Animations — matchMedia()](#responsive-animations--matchmedia) 11. [Plugins Overview](#plugins-overview) 12. [ScrollTrigger](#scrolltrigger) 13. [ScrollSmoother](#scrollsmoother) 14. [Flip Plugin](#flip-plugin) 15. [SplitText Plugin](#splittext-plugin) 16. [React Integration — useGSAP()](#react-integration--usegsap) 17. [Performance Tips & Best Practices](#performance-tips--best-practices) 18. [Helper Functions](#helper-functions)

---

Installation & TypeScript Setup

npm install gsap

TypeScript definitions are bundled with the package. If you need to point your compiler to them explicitly:

// tsconfig.json
{
  "compilerOptions": { ... },
  "files": [
    "node_modules/gsap/types/index.d.ts"
  ]
}

**Basic import:**

import { gsap } from "gsap";

**Importing plugins:**

import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { Flip } from "gsap/Flip";
import { SplitText } from "gsap/SplitText";
import { ScrollSmoother } from "gsap/ScrollSmoother";
import { DrawSVGPlugin } from "gsap/DrawSVGPlugin";

// Register all plugins once, before use
gsap.registerPlugin(ScrollTrigger, Flip, SplitText, ScrollSmoother);

**Recommended: single `gsap.ts` barrel file** to avoid duplicate registrations in large projects:

// gsap.ts
export * from "gsap";
export * from "gsap/ScrollTrigger";
export * from "gsap/Flip";

import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { Flip } from "gsap/Flip";

gsap.registerPlugin(ScrollTrigger, Flip);

Then in other files:

import { gsap, ScrollTrigger } from "../gsap";

**UMD/dist format** (for older build tools that don't support ES modules):

import { gsap } from "gsap/dist/gsap";
import { ScrollTrigger } from "gsap/dist/ScrollTrigger";

> **Tree shaking:** Always call `gsap.registerPlugin(...)` to prevent build tools from dropping plugins during tree shaking. It's safe to register the same plugin multiple times.

---

Core Concepts

GSAP has two primary animation primitives:

**Tween** — animates properties on target(s). Created with `gsap.to()`, `gsap.from()`, or `gsap.fromTo()`.

**Timeline** — a container for sequencing multiple tweens and other timelines. Created with `gsap.timeline()`.

Both extend an `Animation` base class and share the same control methods (`play`, `pause`, `reverse`, `seek`, `timeScale`, etc.).

GSAP can animate **any numeric property** of any JavaScript object — not just CSS. DOM elements, canvas contexts, WebGL uniforms, plain objects — anything works.

**Transform shorthand** — GSAP provides shorthand properties that map to CSS transforms:

| GSAP property | CSS equivalent | | --------------------------- | -------------------------------- | | `x`, `y` | `translateX`, `translateY` | | `xPercent`, `yPercent` | `translateX(%)`, `translateY(%)` | | `rotation` | `rotate` (degrees) | | `rotationX`, `rotationY` | `rotateX`, `rotateY` | | `scale`, `scaleX`, `scaleY` | `scale` | | `skewX`, `skewY` | `skew` |

---

Tweens

// Animate TO values
gsap.to(".selector", {
  x: 100,
  y: 50,
  rotation: 360,
  backgroundColor: "red", // camelCase CSS
  duration: 1, // seconds (default: 0.5)
  delay: 0.5,
  ease: "power2.inOut",
  stagger: 0.1, // offset start per target
  paused: false,
  overwrite: "auto", // "auto" | true | false
  repeat: 2, // -1 = infinite
  repeatDelay: 1,
  repeatRefresh: true, // re-evaluate dynamic values each repeat
  yoyo: true, // A→B→A ping-pong
  yoyoEase: "power1.in", // separate ease for reverse
  immediateRender: false,
  onStart: () => {},
  onUpdate: () => {},
  onComplete: () => {},
  onRepeat: () => {},
  onReverseComplete: () => {},
});

// Animate FROM values (immediateRender: true by default)
gsap.from(".selector", { x: -200, opacity: 0, duration: 1 });

// Animate from → to (define both explicitly)
gsap.fromTo(
  ".selector",
  { x: -200, opacity: 0 },
  { x: 0, opacity: 1, duration: 1 },
);

// Set immediately (no animation)
gsap.set(".selector", { x: 100, opacity: 0 });

**Function-based values** — called once per target, returning the value to use:

gsap.to(".box", {
  x: (index, target, targets) => index * 100,
  duration: 1,
});

**Random values:**

gsap.to(".box", {
  x: "random(-100, 100)", // random number in range
  x: "random(-100, 100, 5)", // rounded to nearest 5
  x: "random([0, 100, 200])", // random from array
});

**Relative values:**

gsap.to(".box", { x: "+=50", rotation: "-=30" });

**Keyframes:**

gsap.to(".box", {
  keyframes: [
    { x: 100, duration: 1 },
    { y: 50, duration: 0.5 },
    { opacity: 0, duration: 0.5 },
  ],
});

**Special properties:**

| Property | Description | | ------------------- | ------------------------------------------- | | `duration` | Duration in seconds (default `0.5`) | | `delay` | Delay before start (seconds) | | `ease` | Easing function name or function | | `stagger` | Start time offset per target | | `repeat` | Number of repeats (`-1` = infinite) | | `repeatDelay` | Pause between repeats | | `yoyo` | Ping-pong direction on repeat | | `paused` | Start paused | | `overwrite` | Kill confl