Gsap Animation

GSAP Animation

When to Use

• Animating DOM elements with precise timing (entrance, exit, state change).
• Building multi-step animation sequences with timelines.
• Creating scroll-driven animations (parallax, pin, scrub).
• Staggering a list of child elements for choreographed reveals.
• Replacing CSS transitions when you need fine-grained control, callbacks, or sequencing.

Key Concepts

Tweens

A tween is a single animation applied to one or more targets.

Timelines

A timeline is a sequencing container for tweens.

const tl = gsap.timeline({ defaults: { duration: 0.6, ease: "power2.out" } });

tl.from(".hero-title", { y: 40, opacity: 0 })
  .from(".hero-subtitle", { y: 30, opacity: 0 }, "-=0.3")   // overlap by 0.3s
  .from(".hero-cta", { scale: 0.8, opacity: 0 }, "-=0.2");

Position parameters control overlap:

Easing

GSAP ships a rich library of eases.

ScrollTrigger

Register the plugin before use:

import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

Core properties:

Stagger

Animate a set of elements with sequential delays:

gsap.from(".card", {
  y: 60,
  opacity: 0,
  duration: 0.5,
  stagger: 0.12,          // 120 ms between each card
  ease: "power2.out",
});

Advanced stagger object:

stagger: {
  each: 0.1,
  from: "center",   // "start" | "end" | "center" | "edges" | "random"
  grid: "auto",     // auto-detect grid layout
  ease: "power1.in" // ease the stagger distribution itself
}

Quick Recipes

Hero Entrance Animation

import gsap from "gsap";

function animateHero() {
  const tl = gsap.timeline({ defaults: { ease: "power3.out" } });

  tl.from(".hero-bg", { scale: 1.2, opacity: 0, duration: 1.2 })
    .from(".hero-title", { y: 60, opacity: 0, duration: 0.8 }, "-=0.6")
    .from(".hero-subtitle", { y: 40, opacity: 0, duration: 0.6 }, "-=0.4")
    .from(".hero-cta", { y: 20, opacity: 0, duration: 0.5 }, "-=0.3");

  return tl; // return so callers can chain or control
}

Sequenced Timeline with Labels

const master = gsap.timeline();

master
  .addLabel("intro")
  .from(".logo", { scale: 0, duration: 0.6, ease: "back.out(1.7)" }, "intro")
  .from(".nav-link", { y: -20, opacity: 0, stagger: 0.08 }, "intro+=0.3")
  .addLabel("content")
  .from(".section-heading", { x: -40, opacity: 0, duration: 0.5 }, "content")
  .from(".section-body", { y: 30, opacity: 0, duration: 0.6 }, "content+=0.2");

Scroll-Scrub Pinned Section

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

gsap.to(".horizontal-panels", {
  xPercent: -100 * (panels.length - 1),
  ease: "none",
  scrollTrigger: {
    trigger: ".horizontal-container",
    pin: true,
    scrub: 1,
    snap: 1 / (panels.length - 1),
    end: () => "+=" + document.querySelector(".horizontal-container").offsetWidth,
  },
});

Scroll-Triggered Fade-In Sections

gsap.utils.toArray(".fade-section").forEach((section) => {
  gsap.from(section, {
    y: 50,
    opacity: 0,
    duration: 0.8,
    ease: "power2.out",
    scrollTrigger: {
      trigger: section,
      start: "top 85%",
      toggleActions: "play none none none",
    },
  });
});

Cleanup Pattern (SPA / React)

import { useEffect, useRef } from "react";
import gsap from "gsap";

function AnimatedComponent() {
  const containerRef = useRef(null);

  useEffect(() => {
    const ctx = gsap.context(() => {
      gsap.from(".box", { x: -100, opacity: 0, stagger: 0.15 });
    }, containerRef); // scope selectors to this container

    return () => ctx.revert(); // kills all tweens created inside
  }, []);

  return (
    <div ref={containerRef}>
      <div className="box">A</div>
      <div className="box">B</div>
    </div>
  );
}

Common Pitfalls

Best Practices

1. Set timeline defaults. Declare shared duration, ease, and stagger in gsap.timeline({ defaults: {} }) to reduce repetition.
2. Return timelines from functions. This lets parent timelines nest them and makes testing easier.
3. Use gsap.context() in component-based frameworks. It scopes selectors and simplifies cleanup.
4. Batch ScrollTrigger refreshes. After dynamic DOM changes call ScrollTrigger.refresh() once, not per element.
5. Prefer relative position parameters ("-=0.3", "<") over absolute seconds so sequences stay intact when durations change.
6. Test with tl.timeScale(0.25) to slow down complex sequences during development and catch timing issues.
7. Respect reduced motion. Wrap animations in a check:

   const prefersReduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   if (!prefersReduced) { animateHero(); }
   

8. Load GSAP from npm (npm install gsap) and tree-shake only the plugins you need to keep bundle size minimal.