Chapter 185: Track Playhead Direction of Any Animation (Helper)

Core Idea

GSAP has no built-in onReverse() callback; this helper detects direction changes on any animation (even deeply nested inside parent timelines whose own reversal/negative timeScale affects it) by comparing each frame's totalTime() to the previous one.

Key Concepts

• trackDirection({ animation, onUpdate, onToggle }) (or pass a plain callback as value for direct onUpdate usage) hooks the animation's onUpdate via eventCallback.
• Sets this.direction (1 or -1) on the animation every frame; onToggle fires only when the direction actually flips, onUpdate fires every frame.
• Works correctly regardless of nesting depth because it derives direction purely from the animation's own totalTime() trend, not from assumptions about its parent.

Key Takeaways

1. Use this whenever you need to react specifically to a reversal, not just to progress changing.

Connects To

• Timeline/Tween eventCallback(): the core mechanism this helper is built on.