Gsap

by AThevon1f518a71378b15d423389e546e767cffc86e14c3No license431 starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 3 days ago

GSAP animation engine sub-skill - core, timeline, ScrollTrigger, plugins.

Instructions onlySoftware Development

AI-generated overview

Reference guidance for using the GSAP animation library, covering core tweens, timelines, ScrollTrigger and plugins.

What it does: This skill is an instruction-only reference for the GSAP 3 animation engine. It explains when to choose GSAP over CSS transitions or Framer Motion, how to register plugins, and how to write core tween, timeline, stagger and ScrollTrigger patterns. It also lists common mistakes to avoid and points to four bundled reference files covering core, timeline, ScrollTrigger and plugins.
When to use it: Use it when building web animations that need sequenced timelines, scroll-linked effects, distributed staggers, text splitting or SVG morphing. It is also useful for checking GSAP setup and plugin registration, or for reviewing animation code against known pitfalls.
Requirements: No scripts are shipped; it is instructions plus four markdown reference files. Applying the guidance assumes a JavaScript project with the gsap npm package, and optionally @gsap/react for React useGSAP usage.

Version-sensitive. Every API name, SDK gate and browser-support claim below was verified on 2026-09-08 against primary sources. What against, and when, is in _jutsu/VERSIONS.md. If that date is old, re-verify before acting on a version number.

GSAP - Animation Engine

GSAP 3.15 (released 13 Apr 2026). Since 3.13 the entire library - including every former Club plugin (SplitText, MorphSVG, DrawSVG, ScrollSmoother, InertiaPlugin, MotionPathHelper, CustomEase…) - ships in the public gsap npm package and is free, commercial use included, under the GreenSock Standard "no charge" license. There is no Club paywall. GreenSock also publish official agent skills (MIT, 8 skills: core, timeline, scrolltrigger, plugins, utils, react, performance, frameworks): https://github.com/greensock/gsap-skills - worth installing alongside this sub-skill.

When to use GSAP

Criteria	CSS Transitions	Framer Motion	GSAP
Hover / simple toggle	Yes	Yes	Overkill
Sequenced timeline	No	Limited	Yes
Scroll-driven	scroll-timeline	Limited	ScrollTrigger
Complex stagger	No	Basic	Distribution
Mobile perf (60fps)	Good	Average	Excellent
Text splitting	No	No	SplitText
SVG morph / draw	No	No	MorphSVG
Bundle size concern	0kb	~30kb	~25kb + plugins

Rule: if the animation needs timeline, scroll-link, or distributed stagger, use GSAP. Otherwise CSS first.

Setup

// Always register plugins at the top levelimport gsap from "gsap";import { ScrollTrigger } from "gsap/ScrollTrigger";import { SplitText } from "gsap/SplitText";
gsap.registerPlugin(ScrollTrigger, SplitText);

// Always register plugins at the top levelimport gsap from "gsap";import { ScrollTrigger } from "gsap/ScrollTrigger";import { SplitText } from "gsap/SplitText";
gsap.registerPlugin(ScrollTrigger, SplitText);

React: use useGSAP() from the @gsap/react package instead of useEffect + manual cleanup.

jsx

import { useGSAP } from "@gsap/react";
useGSAP(() => {  gsap.to(".box", { x: 200 });}, { scope: containerRef }); // auto-cleanup, auto-revert

import { useGSAP } from "@gsap/react";
useGSAP(() => {  gsap.to(".box", { x: 200 });}, { scope: containerRef }); // auto-cleanup, auto-revert

Core Patterns

defaults{} to avoid repetition

const tl = gsap.timeline({  defaults: { duration: 0.8, ease: "power2.out" },});tl.to(".a", { y: -20 })  .to(".b", { y: -20 }, "<0.1")  .to(".c", { y: -20 }, "<0.1");

const tl = gsap.timeline({  defaults: { duration: 0.8, ease: "power2.out" },});tl.to(".a", { y: -20 })  .to(".b", { y: -20 }, "<0.1")  .to(".c", { y: -20 }, "<0.1");

fromTo for full control

Stagger with distribution

gsap.to(".grid-item", {  scale: 0,  stagger: {    each: 0.05,    from: "center",   // "start" | "end" | "center" | "edges" | "random" | index    grid: "auto",      // auto-detects the grid    axis: "x",         // "x" | "y" | null (both)  },});

gsap.to(".grid-item", {  scale: 0,  stagger: {    each: 0.05,    from: "center",   // "start" | "end" | "center" | "edges" | "random" | index    grid: "auto",      // auto-detects the grid    axis: "x",         // "x" | "y" | null (both)  },});

ScrollTrigger Patterns

Basic Pin + Scrub

gsap.to(".panel", {  x: "-300%",  ease: "none",  scrollTrigger: {    trigger: ".container",    pin: true,    scrub: 1,    end: () => "+=" + document.querySelector(".container").scrollWidth,  },});

gsap.to(".panel", {  x: "-300%",  ease: "none",  scrollTrigger: {    trigger: ".container",    pin: true,    scrub: 1,    end: () => "+=" + document.querySelector(".container").scrollWidth,  },});

Batch for mass reveal

ScrollTrigger.batch(".card", {  onEnter: (elements) => gsap.to(elements, { opacity: 1, y: 0, stagger: 0.1 }),  start: "top 85%",});

ScrollTrigger.batch(".card", {  onEnter: (elements) => gsap.to(elements, { opacity: 1, y: 0, stagger: 0.1 }),  start: "top 85%",});

Horizontal scroll with containerAnimation

const scrollTween = gsap.to(".panels", {  x: () => -(document.querySelector(".panels").scrollWidth - window.innerWidth),  ease: "none",  scrollTrigger: { trigger: ".wrapper", pin: true, scrub: 1 },});
// Animate elements INSIDE the horizontal scrollgsap.to(".panel-content", {  scale: 1.2,  scrollTrigger: {    trigger: ".panel-content",    containerAnimation: scrollTween, // linked to horizontal scroll    start: "left center",    end: "right center",    scrub: true,  },});

const scrollTween = gsap.to(".panels", {  x: () => -(document.querySelector(".panels").scrollWidth - window.innerWidth),  ease: "none",  scrollTrigger: { trigger: ".wrapper", pin: true, scrub: 1 },});
// Animate elements INSIDE the horizontal scrollgsap.to(".panel-content", {  scale: 1.2,  scrollTrigger: {    trigger: ".panel-content",    containerAnimation: scrollTween, // linked to horizontal scroll    start: "left center",    end: "right center",    scrub: true,  },});

DO NOT - Critical mistakes

1. Ease on containerAnimation

// BAD - ease breaks the scroll mappingscrollTrigger: { containerAnimation: scrollTween, scrub: 1, ease: "power2.out" }
// GOOD - always ease: "none" on the parent tweenconst scrollTween = gsap.to(".panels", { x: ..., ease: "none", scrollTrigger: { scrub: 1 } });

// BAD - ease breaks the scroll mappingscrollTrigger: { containerAnimation: scrollTween, scrub: 1, ease: "power2.out" }
// GOOD - always ease: "none" on the parent tweenconst scrollTween = gsap.to(".panels", { x: ..., ease: "none", scrollTrigger: { scrub: 1 } });

2. ScrollTrigger on a child tween in a timeline

// BAD - ScrollTrigger ignores child tweens of a timeline that has its own ScrollTriggerconst tl = gsap.timeline({ scrollTrigger: { trigger: ".section" } });tl.to(".box", { x: 100, scrollTrigger: { trigger: ".box" } }); // IGNORE
// GOOD - one ScrollTrigger per timeline OR standalone tweensgsap.to(".box", { x: 100, scrollTrigger: { trigger: ".box" } }); // tween standalone

// BAD - ScrollTrigger ignores child tweens of a timeline that has its own ScrollTriggerconst tl = gsap.timeline({ scrollTrigger: { trigger: ".section" } });tl.to(".box", { x: 100, scrollTrigger: { trigger: ".box" } }); // IGNORE
// GOOD - one ScrollTrigger per timeline OR standalone tweensgsap.to(".box", { x: 100, scrollTrigger: { trigger: ".box" } }); // tween standalone

3. setState in onUpdate

// BAD - setState 60x/s = re-render hellscrollTrigger: { onUpdate: (self) => setProgress(self.progress) }
// GOOD - mutate a ref or DOM element directlyconst progressRef = useRef(0);scrollTrigger: { onUpdate: (self) => { progressRef.current = self.progress; } }// Or better: gsap.quickSetter to mutate the DOM without React

// BAD - setState 60x/s = re-render hellscrollTrigger: { onUpdate: (self) => setProgress(self.progress) }
// GOOD - mutate a ref or DOM element directlyconst progressRef = useRef(0);scrollTrigger: { onUpdate: (self) => { progressRef.current = self.progress; } }// Or better: gsap.quickSetter to mutate the DOM without React

4. immediateRender on from() in a timeline

// BAD - from() has immediateRender: true by default, breaks sequencingtl.to(".box", { x: 100 });tl.from(".box", { y: 50 }); // visually jumps to the start
// GOOD - disable immediateRender when from() follows another tweentl.to(".box", { x: 100 });tl.from(".box", { y: 50, immediateRender: false });

// BAD - from() has immediateRender: true by default, breaks sequencingtl.to(".box", { x: 100 });tl.from(".box", { y: 50 }); // visually jumps to the start
// GOOD - disable immediateRender when from() follows another tweentl.to(".box", { x: 100 });tl.from(".box", { y: 50, immediateRender: false });

5. Animating non-transform properties

// BAD - width/height/top/left trigger layout reflowgsap.to(".box", { width: 200, height: 200 });
// GOOD - use transforms (GPU-accelerated, composited)gsap.to(".box", { scaleX: 1.5, scaleY: 1.5 });// If actual size needed: use Flip plugin for layout transition

// BAD - width/height/top/left trigger layout reflowgsap.to(".box", { width: 200, height: 200 });
// GOOD - use transforms (GPU-accelerated, composited)gsap.to(".box", { scaleX: 1.5, scaleY: 1.5 });// If actual size needed: use Flip plugin for layout transition

Refs

references/core.md - Complete gsap.to/from/fromTo/set API, options
references/timeline.md - Timeline, position parameter, nesting
references/scrolltrigger.md - Full ScrollTrigger reference
references/plugins.md - SplitText, Flip, MorphSVG, DrawSVG, MotionPath, Observer

Source and attribution

Source:AThevon/genjutsuinskills/_jutsu/gsapat commit1f518a7

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Gsap

GSAP - Animation Engine

When to use GSAP

Setup

Core Patterns

defaults{} to avoid repetition

fromTo for full control

Stagger with distribution

ScrollTrigger Patterns

Basic Pin + Scrub

Batch for mass reveal

Horizontal scroll with containerAnimation

DO NOT - Critical mistakes

1. Ease on containerAnimation

2. ScrollTrigger on a child tween in a timeline

3. setState in onUpdate

4. immediateRender on from() in a timeline

5. Animating non-transform properties

Refs

Source and attribution

More from AThevon/genjutsu

Framer Motion

Css Native

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices