.staggerFromTo()

Tweens multiple targets from and to a common set of 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 fade from opacity:1 to opacity:0 in a staggered fashion with 0.2 seconds between each tween's start time:

myTimeline.staggerFromTo(".class", 1, {opacity:1}, {opacity:0}, 0.2);

staggerFromTo() simply loops through the targets array and creates a fromTo() tween for each object and then inserts it at the appropriate place on a new TimelineLite instance whose onComplete corresponds to the onCompleteAll (if you define one) and then appends that TimelineLite to the timeline (as a nested child).

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:
myTimeline.staggerFromTo(".class", 1, {opacity:0}, {opacity:1}, 0.2);
myTimeline.staggerFromTo(".class", 1, {opacity:0}, {opacity:1, stagger:0.2});

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 7th parameter).

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.

The 6th parameter is the position which controls the placement of the tweens in the timeline (by default, it's at the end of the timeline). See https://greensock.com/position-parameter for details. Use a number to indicate an absolute time in terms of seconds, or you can use a string with a "+=" or "-=" prefix to offset the insertion point relative to the END of the timeline. For example,"+=2" would place the first tween 2 seconds after the end, leaving a 2-second gap. "-=2" would create a 2-second overlap. You may also use a label like "myLabel" to have the first tween inserted exactly at the label or combine a label and a relative offset like "myLabel+=2" to insert the first tween 2 seconds after "myLabel" or "myLabel-=3" to insert it 3 seconds before "myLabel". If you define a label that doesn't exist yet, it will automatically be added to the end of the timeline before inserting the tweens there which can be quite convenient.

tl.staggerFromTo(myArray, 1, {left:0}, {left:100}, 0.25);  //appends to the end of the timeline
tl.staggerFromTo(myArray, 1, {left:0}, {left:100}, 0.25, 2);  //appends at exactly 2 seconds into the timeline (absolute position)
tl.staggerFromTo(myArray, 1, {left:0}, {left:100}, 0.25, "+=2");  //appends 2 seconds after the end (with a gap of 2 seconds)
tl.staggerFromTo(myArray, 1, {left:0}, {left:100}, 0.25, "myLabel");  //places at "myLabel" (and if "myLabel" doesn't exist yet, it's added to the end and then the tweens are inserted there)
tl.staggerFromTo(myArray, 1, {left:0}, {left:100}, 0.25, "myLabel+=2");  //places 2 seconds after "myLabel"

Be sure to read our tutorial Understanding the Position Parameter which includes interactive timeline visualizations and a video.

NOTE: by default, immediateRender is true in staggerFromTo() tweens, meaning that they immediately render their starting state regardless of any delay that is specified. This is done for convenience because it is often the preferred behavior when setting things up on the screen to animate into place, but you can override this behavior by passingimmediateRender:false in the fromVars or toVars parameter so that it will wait to render the starting values until the tweens actually begin.

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).

*note TimelineLite.staggerFromTo() and TimelineMax.staggerFromTo() use identical syntax.

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 tl.staggerFromTo(".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+