GSAP

Quick reference for setting up and using GSAP across projects.

Install

Since GSAP v3.13+, all plugins (including premium ones like ScrollSmoother and SplitText) are available directly from public npm. No private registry or auth token needed.

npm install gsap

Plugin Registration

Import and register all plugins before use:

import { gsap } from "gsap";

import { Draggable } from "gsap/Draggable";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { ScrollSmoother } from "gsap/ScrollSmoother";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { SplitText } from "gsap/SplitText";

gsap.registerPlugin(Draggable, ScrollTrigger, ScrollSmoother, ScrollToPlugin, SplitText);

Plugins

Best Practices

Always Check Elements Exist

const el = document.querySelector('.target');
if (!el) return;

Respect Reduced Motion

if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
  gsap.set(element, { opacity: 1 });
  return;
}

Use GPU Acceleration for 3D

gsap.to(el, {
  scale: 0.8,
  rotationZ: 15,
  force3D: true
});

Debounce ScrollTrigger Refresh

Call ScrollTrigger.refresh() after DOM changes, but debounce it (150ms minimum).

Prevent Duplicate Animations

Mark elements after processing to avoid re-binding:

if (el.dataset.bound) return;
// ... animate ...
el.dataset.bound = "1";

Cache SplitText Instances

Don't re-split on every animation — cache and revert on resize:

const cache = new Map();
const split = cache.get(el) || new SplitText(el, { type: "words" });
cache.set(el, split);

// On resize:
split.revert();

ScrollSmoother — Non-Touch Only

if (!("ontouchstart" in window)) {
  ScrollSmoother.create({ smooth: 1, effects: true });
}

Easing

Use power2.out as the default. Reserve power3.out or power4.out for snappy/aggressive effects.

Performance

• Limit scrub animations to 3–4 per page
• Avoid SplitText on large text blocks
• Wait for fonts before splitting text (document.fonts.ready)
• Use markers: true during development, remove in production