Chapter 32: gsap.timeline()

Core Idea

gsap.timeline() creates a Timeline — a container that sequences tweens/timelines with precise relative timing, replacing fragile manual delay chains.

Key Concepts

• Returns: a Timeline instance.
• Delay-chain problem: without timelines, changing one animation's duration forces you to manually recalculate every later tween's delay.
• repeat / repeatDelay: timeline-level options to loop the whole sequence.
• Whole-sequence control: pause(), restart(), reverse() operate on everything inside the timeline at once.

Code Examples

// without timelines — fragile delay chain
gsap.to("#id", { x: 100, duration: 1 });
gsap.to("#id", { y: 50, duration: 1, delay: 1 });
gsap.to("#id", { opacity: 0, duration: 1, delay: 2 });

// with a timeline — durations auto-cascade, whole thing is controllable
let tl = gsap.timeline({ repeat: 2, repeatDelay: 1 });
tl.to("#id", { x: 100, duration: 1 });
tl.to("#id", { y: 50, duration: 1 });

• What it demonstrates: the same two-step sequence built with brittle delays vs. a timeline where changing the first tween's duration automatically shifts everything after it.

Key Takeaways

1. Any sequencing more complex than a single tween should almost always use a Timeline instead of manual delay math.
2. Because a timeline is itself controllable as a unit, pausing/reversing/repeating a whole multi-step animation is trivial.

Connects To

• Timeline chapters: full method reference (.to(), .add(), labels, .play(), etc.).