Jump to content
GreenSock

Search In
  • More options...
Find results that contain...
Find results in...

TimelineLite

.staggerTo()

.staggerTo( targets:Array, duration:Number, vars:Object, stagger:Number | Object | Function, position:*, onCompleteAll:Function, onCompleteAllParams:Array, onCompleteScope:* ) : *

Tweens an array of targets to a common set of destination values, but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code.

Parameters

targets: Array

An array of objects whose properties should be affected. When animating DOM elements, the targets can be: an array of elements, a jQuery object (or similar), or a CSS selector string like “.myClass” or “h2.author”. GSAP will pass selector strings to a selector engine like jQuery or Sizzle (if one is detected or defined through TweenLite.selector), falling back to document.querySelectorAll().

duration: Number

Duration in seconds (or frames if the timeline is frames-based)

vars: Object

An object defining the end value for each property that should be tweened as well as any special properties like ease. For example, to tween left to 100 and topto 200 for element1, element2, and element3, staggering their start time by 0.25 seconds and then call myFunction when they last one has finished, do this:myTimeline.staggerTo([element1, element2, element3], 1, {left:100, top:200}, 0.25, 0, null, myFunction}).

Show More

stagger: Number | Object | Function

(default = 0)— Amount of time (in seconds) to stagger the start time of each tween. As of version 2.1, you may also use an advanced stagger object which accommodates grids, uneven spacing, and doing things like emanating out from the center. See https://codepen.io/GreenSock/full/jdawKx for an interactive demo and details.

position: *

(default = +=0) — Controls the placement of the first tween in the timeline (by default, it’s the end of the timeline, like “+=0”). Use a number to indicate an absolute time in terms of seconds (or frames for frames-based timelines), 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 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 tween inserted exactly at the label or combine a label and a relative offset like "myLabel+=2" to insert the 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 tween there which can be quite convenient. Be sure to read our tutorial Understanding the Position Parameter which includes interactive timeline visualizations and a video.

onCompleteAll: Function

(default = null) — A function to call as soon as the entire sequence of tweens has completed

onCompleteAllParams: Array

(default = null) — An array of parameters to pass the onCompleteAll method.

onCompleteScope: *

The scope for the onCompleteAll function call (what “this” should refer to inside that function)

Returns : *

self (makes chaining easier)

 

Details

Tweens multiple 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  and fade out in a staggered fashion with 0.2 seconds between each tween's start time:

myTimeline.staggerTo(".class", 1, {top:"+=150", opacity:0, ease:CubicIn.ease}, 0.2);

staggerTo() simply loops through the targets array and creates a to() tween for each 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.staggerTo(".class", 1, {y:300}, 0.2);
myTimeline.staggerTo(".class", 1, {y:300, 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 6th 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 5th 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 which can be quite convenient.

tl.staggerTo(myArray, 1, {left:100}, 0.25);  //appends to the end of the timeline
tl.staggerTo(myArray, 1, {left:100}, 0.25, 2);  //appends at exactly 2 seconds into the timeline (absolute position)
tl.staggerTo(myArray, 1, {left:100}, 0.25, "+=2");  //appends 2 seconds after the end (with a gap of 2 seconds)
tl.staggerTo(myArray, 1, {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.staggerTo(myArray, 1, {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.

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.staggerTo() and TimelineMax.staggerTo() 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.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+
Copyright 2017, GreenSock. All rights reserved. This work is subject to theterms of useor for Club GreenSock members, the software agreement that was issued with the membership.
×