Chapter 178: Progressively Build a Timeline Step-by-Step (Helper)

Core Idea

A helper for cases where the full timeline can't be pre-built up front because each step's animation depends on running a function first (e.g. changing state) and must fully complete before the next step's function runs; it lets you express that as a flat sequence of functions and optional delays.

Key Concepts

• Call progressiveBuild(step1, step2, delayNumber, step3, ...) — each function returns the tween/timeline for that step; a bare number between two functions becomes a delay before the next step's added.
• Internally uses a repeating onComplete that pulls the next function/delay off the argument list and appends its result to the timeline with "+=" + delay.

Code Examples

function progressiveBuild() {
  let data = Array.from(arguments), i = 0,
    tl = gsap.timeline({
      onComplete: function () {
        let isNum = typeof data[i] === "number",
          delay = isNum ? data[i++] : 0,
          func = data[i++];
        typeof func === "function" && tl.add(func(), "+=" + delay);
      },
    });
  tl.vars.onComplete();
  return tl;
}

progressiveBuild(step1, step2, 1.5, step3);

• What it demonstrates: chaining steps whose animations aren't known until the previous step's function actually runs.

Key Takeaways

1. Use this only when steps genuinely can't be pre-built as one timeline; otherwise a normal timeline.add() sequence is simpler.

Connects To

• Timeline (core): this helper is a thin orchestration layer on top of a normal Timeline.