GSAP AI Skills

The scrub property ties the progress of an animation directly to the scrollbar position.

• scrub: true: The animation progress is directly linked to the scroll position.
• scrub: <number>: The animation follows the scroll position with a delay of <number> seconds, creating a smooth 'catching up' effect.

gsap.to(".box", {
  x: 500,
  scrollTrigger: {
    trigger: ".box",
    start: "top center",
    end: "bottom center",
    scrub: 1 // smooth lag of 1 second
  }
});

The start and end properties define when a ScrollTrigger becomes active. They accept strings, numbers, or functions.

• Format: "triggerPosition viewportPosition" (e.g., "top center", "bottom 80%").
• Numeric values: A number like 500 represents pixels from the top of the scroller.
• Relative values: Use "+=300" (300px past start) or "+=100%" (scroller height past start).
• Clamp: Use clamp() (v3.12+) to keep triggers within page bounds, e.g., start: "clamp(top bottom)".
• Functions: You can pass a function that receives the ScrollTrigger instance and returns a value. If the layout changes, call ScrollTrigger.refresh() to recalculate positions.

When using GSAP with component-based frameworks (Vue, Svelte, etc.), follow these three core principles to prevent memory leaks and selector collisions:

1. Create after mounting: Always initialize tweens and ScrollTrigger instances inside lifecycle hooks that run after the DOM is available (e.g., onMounted in Vue, onMount in Svelte).
2. Scope selectors: Use gsap.context(callback, scope) where scope is your component's root element. This ensures selectors like .box only target elements within that specific component instance.
3. Cleanup on unmount: Always call ctx.revert() in the component's unmount/destroy lifecycle hook. This kills all animations and ScrollTrigger instances tracked by that context and reverts inline styles.

To prevent GSAP from selecting elements outside your component, always provide a scope to gsap.context().

• Correct: gsap.context(() => { gsap.to(".box", { ... }) }, containerRef) — The selector .box is restricted to the containerRef subtree.
• Incorrect: gsap.to(".box", { ... }) — This uses a global selector and may animate elements in other components or elsewhere on the page.

// Scoped to the container
ctx = gsap.context(() => {
  gsap.to(".box", { x: 100 });
}, container.value);

To prevent jank when dealing with large numbers of elements or complex timelines:

• Staggering: Use the stagger property instead of creating many separate tweens with manual delays when the animation logic is the same.
• Virtualization: For long lists, consider animating only visible items or using virtualization to avoid creating hundreds of simultaneous tweens.
• Timeline Reuse: Reuse timelines where possible rather than creating new ones every frame.
• Cleanup: Always kill or pause off-screen or inactive animations when they are no longer visible to prevent stray tweens from consuming resources.

Timelines can be treated as single units and added to other timelines using the .add() method. This is useful for building complex, modular animation structures.

const master = gsap.timeline();
const child = gsap.timeline();

child.to(".a", { x: 100 }).to(".b", { y: 50 });

// Add the child timeline to the master at time 0
master.add(child, 0);
master.to(".c", { opacity: 0 }, "+=0.2");

Many gsap.utils methods allow you to create reusable functions by omitting the final value argument. This is highly efficient for high-frequency operations like mousemove handlers or tween callbacks where the configuration (like a range or a snap increment) remains constant while the input value changes.

Note on random(): Unlike other utilities, random() does not use the omission pattern. To get a reusable function from random(), you must pass true as the last argument (returnFunction).

// Standard pattern: omit the last argument to get a function
let c = gsap.utils.clamp(0, 100);
c(150); // 100

// Exception: random() requires 'true' as the last argument
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn(); // returns a new random value

GSAP allows for dynamic values and relative adjustments within the vars object.

Function-based values

If a property value is a function, it is called once for each target during the first render. The return value is used for that specific target.

Relative values

Use prefixes to indicate relative changes to the current value:

• +=n: Add n to current value.
• -=n: Subtract n from current value.
• *=n: Multiply current value by n.
• /=n: Divide current value by n.

// Function-based: each item moves based on its index
gsap.to(".item", {
  x: (i, target, targetsArray) => i * 50
});

// Relative: move 20px less than current position
gsap.to(".class", { x: "-=20" });

Animations created inside functions that execute after the initial useGSAP run (such as event listeners) are not automatically tracked by the GSAP context. To ensure these animations are cleaned up on unmount, wrap the function in contextSafe provided by the useGSAP hook.

const container = useRef();
const goodRef = useRef();

useGSAP((context, contextSafe) => {
  // ✅ safe, created during execution
  gsap.to(goodRef.current, { x: 100 });

  // ✅ safe, wrapped in contextSafe() so it's tracked by the context
  const onClickGood = contextSafe(() => {
    gsap.to(goodRef.current, { rotation: 180 });
  });

  goodRef.current.addEventListener('click', onClickGood);

  // Clean up the listener manually
  return () => {
    goodRef.current.removeEventListener('click', onClickGood);
  };
}, { scope: container });