Jump to content
GreenSock

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

TweenMax.staggerFrom()

TweenMax.staggerFrom( targets:Array, duration:Number, vars:Object, stagger:Number | Object | Function, onCompleteAll:Function, onCompleteAllParams:Array, onCompleteAllScope:* ) : Array

[static] Tweens an array of targets from a common set of destination values (using the current values as the destination), 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 useFrames:true is defined in the vars parameter)

vars: Object

An object defining the end value for each property that should be tweened as well as any special properties likeease. For example, to tween x to 100 and y to 200 for mc1, mc2, and mc3, staggering their start time by 0.25 seconds and then call myFunction when they last one has finished, do this: TweenMax.staggerTo([mc1, mc2, mc3], 1, {x:100, y:200}, 0.25, 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.

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.

onCompleteAllScope: *

(default = null) — The scope in which the onCompleteAll callback should be called (basically, what “this” refers to in the function). NOTE: this parameter only pertains to the JavaScript and AS2 versions; it is omitted in AS3.

Returns : Array

An array of TweenMax instances (one for each object in the targets array). If you want to control the playback of all the tweens together, consider using TimelineLite/Max's staggerFrom() method since it accomplishes the same thing but inserts them into a single timeline.

Details

Tweens multiple targets from a common set of destination values (using the current values as the destination), but staggers their start times, creating an evenly-spaced sequence with a surprisingly small amount of code. For example, let's say you have a bunch of elements that you'd like to drop into place while fading in, all in a staggered fashion with 0.2 seconds between each tween's start time:

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

staggerFrom() simply loops through the targets array and creates a from() 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.staggerFrom(".class", 1, {y:300}, 0.2);
TweenMax.staggerFrom(".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 staggerFrom() 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).

By default, immediateRender is true in from() tweens, meaning that they immediately render their starting state regardless of any delay that is specified. You can override this behavior by passing immediateRender:false in the vars parameter so that it will wait to render until the tween actually begins.

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.staggerFrom(".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.
×