GSAP Web Animation

Introduction

GSAP is a JavaScript animation library for controlling motion with code. It is useful when CSS transitions or CSS keyframes are not enough for the interaction you want to build.

Use GSAP when you need precise timing, sequences, staggered groups, scroll-based motion, or animations that respond to user interaction.

When to Use GSAP

Choose the simplest tool that handles the job. CSS is still the right choice for many small interactions. GSAP becomes helpful when the timing or interaction gets more complex.

Getting Started with GSAP

You can load GSAP from a CDN for small demos. In larger projects, you may install it through your package manager.

A tween is one animation instruction. It needs a target, properties to animate, and timing options such as duration and ease.

GSAP x and y use transforms. They are usually better for motion than animating layout properties such as left or top.

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>

<div class="box">Animate me</div>

<script>
  gsap.to('.box', {
    x: 100,
    rotation: 360,
    duration: 1,
  });
</script>

Tween Basics

Common GSAP Properties

`gsap.to()`

gsap.to() animates from the element's current state to the values you provide.

gsap.to('.box', {
  x: 120,
  opacity: 0.5,
  duration: 0.6,
  ease: 'power2.out',
});

`gsap.from()`

gsap.from() starts at the values you provide and animates to the element's current CSS state. This is useful for entrance animations.

gsap.from('.card', {
  y: 30,
  opacity: 0,
  duration: 0.6,
  ease: 'power2.out',
});

`gsap.fromTo()`

gsap.fromTo() lets you define both the starting values and ending values. Use it when you need complete control over both states.

gsap.fromTo(
  '.button',
  { scale: 0.8, opacity: 0 },
  { scale: 1, opacity: 1, duration: 0.4 }
);

Timelines

gsap.timeline() lets you sequence multiple tweens without calculating all the delays by hand.

Each tween is added to the timeline. By default, the next tween starts after the previous tween ends.

const timeline = gsap.timeline();

timeline
  .to('.box', { x: 100, duration: 0.5 })
  .to('.box', { rotation: 180, duration: 0.5 })
  .to('.box', { scale: 1.2, duration: 0.5 });

Timeline Position Controls

Timeline position values control when a tween starts. This is one of the biggest reasons to use GSAP for sequenced motion.

const timeline = gsap.timeline();

timeline
  .to('.card', { y: -12, duration: 0.3 })
  .to('.card', { opacity: 1, duration: 0.3 }, '<')
  .to('.badge', { scale: 1, duration: 0.2 }, '-=0.1');

Staggered Tweens

stagger animates a group of elements with a delay between each element. This is great for card grids, navigation items, galleries, and lists.

gsap.from('.gallery-card', {
  y: 24,
  opacity: 0,
  duration: 0.45,
  ease: 'power2.out',
  stagger: 0.08,
});

Easing

ease changes the feel of the motion. Start with common values such as power2.out, power2.inOut, or sine.inOut before using more dramatic easing.

gsap.to('.panel', {
  y: 0,
  opacity: 1,
  duration: 0.5,
  ease: 'power2.out',
});

Callbacks

Callbacks run functions at different points in a tween. Use them when animation needs to coordinate with interface state.

gsap.to('.notification', {
  y: 0,
  opacity: 1,
  duration: 0.3,
  onStart: () => console.log('Animation started'),
  onComplete: () => console.log('Animation complete'),
});

Repeat and Yoyo

repeat controls how many times a tween repeats. yoyo makes alternate repeats play backward.

Use infinite motion carefully. Repeated motion should have a clear purpose and should respect reduced-motion preferences.

gsap.to('.pulse', {
  scale: 1.12,
  duration: 0.8,
  repeat: 3,
  yoyo: true,
  ease: 'sine.inOut',
});

Reduced Motion with GSAP

Check prefers-reduced-motion before running non-essential animation. You can skip the animation, shorten it, or set final states immediately.

const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

if (reduceMotion) {
  gsap.set('.card', { opacity: 1, y: 0 });
} else {
  gsap.from('.card', {
    opacity: 0,
    y: 24,
    duration: 0.5,
    stagger: 0.08,
  });
}

Plugins

GSAP plugins extend what GSAP can do. Use plugins when the core tween and timeline tools are not enough.

Advanced Performance Notes

For most beginner work, animate x, y, scale, rotation, and opacity. These map well to transform and opacity-based motion.

Tools like overwrite, force3D, and CSS will-change can help in specific cases, but they should not be the first thing you reach for.

• overwrite: auto can help when multiple tweens compete for the same properties.
• force3D: true can encourage GPU rendering, but overusing it can hurt performance.
• will-change can prepare the browser for animation, but leaving it everywhere can waste memory.

gsap.to('.box', {
  x: 200,
  duration: 1,
  overwrite: 'auto',
});

Common Mistakes