TweenMax.staggerTo()

Tweens an array of targets to a common set of destination values, but staggers their start times, creating a sequence with a surprisingly small amount of code. For example, let's say you have a bunch of elements that you'd like to fall away and fade out in a staggered fashion with 0.2 seconds between each tween's start time:

TweenMax.staggerTo(".class", 1, {y:"+=150", opacity:0}, 0.2);

staggerTo() simply loops through the targets array and creates a to() tween for each object and then returns an array containing all of the resulting tweens (one for each object).

As of version 2.1, you can pass the stagger value as a special property in the vars object for better readability.

//the following two lines produce identical results starting in version 2.1.0:
TweenMax.staggerTo(".class", 1, {y:300}, 0.2);
TweenMax.staggerTo(".class", 1, {y:300, stagger:0.2});

Advanced staggers

As of version 2.1, you may also use an advanced stagger object which accommodates grids, uneven spacing, and doing things like emanating the timing outward from the center. See below for an interactive demo and details.

If you can afford the slight increase in file size, it is usually better to use TimelineLite/Max's staggerTo() method because it wraps the tweens in a timeline instead of an array which makes controlling the group as a whole much easier. That way you could pause(), resume(), reverse(), restart() or change the timeScale of everything at once.

Note that if you define an onComplete (or any callback for that matter) in the vars parameter, it will be called for each tween rather than the whole sequence. This can be very useful, but if you want to call a function after the entire sequence of tweens has completed, use the onCompleteAll parameter (the 5th parameter).

Due to the way JavaScript doesn't maintain scope (what "this" refers to, or the context) in function calls, it can be useful to define the scope specifically, using the 7th parameter, onCompleteAllScope.

Cycle through multiple values

Instead of defining a single value (like x:100, rotation:90), you can define an Array of values to cycle through (like cycle:{x:[100,-100], rotation:[30,60,90]}) or even use function-based values (like cycle:{x:function() { return Math.random() * 200; }}). The amount of functionality you can pack into a single line of code is staggering (pun intended).

Parameters: index, target

When defining cycle values with functions the functions are passed two parameters:

1. index (integer) - the target's position in the array of targets. For example, if there are 3 <div> elements with the class ".box", and you TweenMax.staggerTo(".box", ...), the function would get called 3 times (once for each target) and the index would be 0 first, then 1, and finally 2.
2. target (object) - the target itself (the <div> element in this case)

Caveats

• The cycle property is available only in the staggerTo(), staggerFrom(), and staggerFromTo() methods in TweenMax, TimelineLite and TimelineMax.
• the cycle property is available in GSAP 1.18.0+