TweenMax

TweenMax extends TweenLite, adding many useful (but non-essential) features like repeat(), repeatDelay(), yoyo(), and more. It also includes many extra plugins by default, making it extremely full-featured. Any of the plugins can work with TweenLite too, but TweenMax saves you the step of loading the common ones like CSSPlugin, RoundPropsPlugin, BezierPlugin, AttrPlugin, DirectionalRotationPlugin as well as EasePack, TimelineLite, and TimelineMax. Since TweenMax extends TweenLite, it can do ANYTHING TweenLite can do plus more. The syntax is identical. You can mix and match TweenLite and TweenMax in your project as you please, but if file size is a concern it is best to stick with TweenLite unless you need a particular TweenMax-only feature.

Like TweenLite, a TweenMax instance handles tweening one or more properties of any object (or array of objects) over time. TweenMax can be used on its own or in conjunction with advanced sequencing tools like TimelineLite or TimelineMax to make complex tasks much simpler. With scores of other animation frameworks to choose from, why consider the GreenSock Animation Platform?:

  • SPEED - The platform has been highly optimized for maximum performance. See some speed comparisons yourself at http://greensock.com/js/speed.html
  • Freakishly robust feature set - In addition to tweening any numeric property of any object, plugins can be activated to tween hex colors, beziers, css, plus LOTS more. It can round values, use relative values, smoothly reverse() on the fly, automatically detect and accommodate getter/setter functions, employ virtually any easing equation, pause()/resume()anytime, and intelligently manage conflicting tweens of the same object with various overwrite modes.
  • Sequencing, grouping, and management features - TimelineLite and TimelineMax make it surprisingly simple to create complex sequences or groups of tweens that you can control as a whole. play(), pause(), restart(), or reverse(). You can even tween a timeline's time() or progress() to fastforward or rewind the entire timeline. Add labels, change the timeline's timeScale, nest timelines within timelines, and much more. This can revolutionize your animation workflow, making it more modular and concise.
  • Ease of use - Designers and developers alike rave about how intuitive the platform is.
  • Support and reliability - With frequent updates, dedicated forums, committed authorship, a solid track record, a proven funding mechanism, and a thriving community of users, the platform is a safe long-term bet (unlike many open source projects).
  • Expandability - With its plugin architecture, you can activate as many (or as few) extra features as your project requires. Write your own plugin to handle particular special properties in custom ways. Minimize bloat and maximize performance.

Getting started

Usage

The most common type of tween is a TweenMax.to() tween which allows you to define the destination values:

var photo = document.getElementById("photo");
TweenMax.to(photo, 2, {width:"200px", height:"150px"});

The above code will tween the width and height properties of the <img> DOM element with an id of "photo" from whatever the current values are to 200 and 150 respectively over the course of 2 seconds. Notice the width and height values are defined inside a generic object (between curly braces). Put as many properties there as you want.

If you pass a string (text) into a tween as the target (like TweenMax.to("#myID", 1, {left:"100px"})) TweenMax will use a selector engine (jQuery if present, or document.querySelectorAll() or lastly, document.getElementById() (automatically removing the "#" prefix if it's there)).

So once TweenMax is loaded, you can easily animate things like this:

//tween the element with ID of "myID"
TweenMax.to("#myID", 2, {backgroundColor:"#ff0000", width:"50%", top:"100px", ease:Power2.easeInOut});
 
//or you can do more advanced selecting like all the elements with the class "myClass" like this: 
TweenMax.to(".myClass", 2, {boxShadow:"0px 0px 20px red", color:"#FC0"});

By default, tweens begin immediately, although you can delay them using the delay special property or pause them initially using the paused special property (see below).

The target can also be an array of objects. For example, the following tween will tween the opacity css property to 0.5 and the rotation transform property to 45 for obj1, obj2, and obj3:

TweenMax.to([obj1, obj2, obj3], 1, {opacity:0.5, rotation:45});

Normally, css-specific properties would need to be wrapped in their own object and passed in like TweenMax.to(element, 1, {css:{left:"100px", top:"50px"}}); so that the engine knows that those properties belong to the CSSPlugin, but because animating DOM elements in the browser with CSSPlugin is so common, TweenMax automatically checks to see if the target is a DOM element and if it is (and you haven't defined a "css" object in the vars), TweenMax creates that css object for you and shifts any properties that aren't directly defined on the element or reserved (like onComplete, ease, delay, etc. or plugins) into that css object when the tween renders for the first time.

You can also use a TweenMax.from() tween if you want to define the starting values instead of the ending values so that the target tweens from the defined values to wherever they currently are. Or a TweenMax.fromTo() lets you define both starting and ending values.

Although the to()from(), and fromTo() static methods are popular because they're quick and can avoid some garbage collection hassles, you can also use the more object-oriented syntax like this:

var tween = new TweenMax(myObject, 2, {width:200, height:150});

or even:

var tween = TweenMax.to(myObject, 2, {width:200, height:150});

Special Properties, callbacks and eases

In addition to handling the destination values of a tween, the vars object allows you to configure your tween with a variety of options.

TweenMax.to(element, 1, {opacity:0, onComplete:completeHandler, ease:Back.easeOut, useFrames:true});

All TweenMax vars' properties are described below.

Plugins

Think of plugins like special properties that are dynamically added, delivering extra abilities without forcing them to be baked into the core engine, keeping it relatively lean and mean. Each plugin is associated with a property name and it takes responsibility for handling that property. For example, the CSSPlugin is associated with the "css" property name so if it is activated it will intercept the "css" property in the following tween and manage it in a special way so that the tweens affect the element's style object (for manipulating DOM elements):

TweenMax.to(element, 1, {css:{top:"100px", left:"50px", backgroundColor:"#ff0000", fontSize:"12px"}, delay:0.5});

But again, CSSPlugin is a special case where TweenMax (as of version 1.8.0) doesn't require wrapping css-specific properties in a css object (although you can if you want maximum performance).

If the CSSPlugin wasn't loaded, TweenMax would act as though you were trying to literally tween the element.css property (and there is no such thing).

The following plugins are automatically activated by TweenMax:

  • css : Object - handles tweening almost any css-related value including backgroundColor, width, height, fontSize, color, top, left, marginTop, etc. Plus it can do transformations like rotation, scaleX, scaleY, skewX, skewY, x, y, xPercent, yPercent and even directionalRotation and autoAlpha. It recognizes transformOrigin and backgroundPosition too. Transformations work in IE7 and later (although those browsers are rather slow at rendering transformations). TweenMax.to(myElement, 1, {width:"50%", height:"300px", backgroundColor:"#ff0000", delay:1});
  • roundProps : String - A comma-delimited list of property names whose value should be rounded to the nearest integer anytime they are updated during the tween. For example, if you're tweening the x, y, and opacity properties of mc and you want to round the x and y values (not opacity) every time the tween is rendered, do: TweenMax.to(mc, 2, {x:300, y:200, opacity:0.5, roundProps:"x,y"});
  • bezier Object - Allows you to animate along a Bezier curve/path. It will even draw a Bezier curve through a set of values that you provide, ensuring that it is smooth. Control the "curviness" too. Or define the Bezier as cubic or quadratic values. This plugin is extremely flexible. It even distributes motion across the Bezier proportionally so that it doesn't suffer from the common problem in most Bezier animation systems where things speed up or slow down at various spots along the path. See the docs for the BezierPlugin for specifics about the syntax and example code.

Function-based values

Instead of a number (x:100) or string (width:"300px") or relative value (y:"+=50"), you can now define most values as a function that'll get called once for each target the first time the tween renders, and whatever is returned by that function will be used as the value. This can be very useful for randomizing things or applying conditional logic. See it in action in the demos below.

Parameters: index, target
The function is 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.to(".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)

Using the index parameter makes it easy to increment the value accordingly. There are lots of ways to get creative. The demo below uses the index parameter to tween each element's x value in increments of 100.

Examples

Please see http://greensock.com/gsap-js/ for examples, tutorials, and interactive demos.

Notes / Tips

  • Passing values as Strings and a preceding "+=" or "-=" will make the tween relative to the current value. For example, if you do TweenMax.to(element, 2, {left:"-=20px"}); it'll tween left to 20 pixels less than whatever it is when the tween starts. {x:"+=20"} would add 20.
  • You can change the default ease by setting the TweenLite.defaultEase static property. The default is Power1.easeOut.
  • You can kill all tweens of a particular object anytime with TweenMax.killTweensOf(yourObject); You can also use selector text like TweenMax.killTweensOf("#someID");
  • You can kill all delayedCalls to a particular function with TweenMax.killDelayedCallsTo(myFunction) or TweenMax.killTweensOf(myFunction);
  • If you find this class useful, please consider joining Club GreenSock which not only helps to sustain ongoing development, but also gets you bonus plugins, classes and other benefits that are ONLY available to members. Learn more at http://greensock.com/club/

Constructor

TweenMax( target:Object, duration:Number, vars:Object ) ;

Constructor

Properties

defaultEase : Ease

[static] Provides An easy way to change the default easing equation.

defaultOverwrite : String = "auto"

[static] Provides An easy way to change the default overwrite mode.

onOverwrite : Function

[static] A function that should be called when any tween gets overwritten by another tween (great for debugging).

selector : * = document.getElementById()

[static] The selector engine (like jQuery) that should be used when a tween receives a string as its target, like TweenLite.to("#myID", 1, {x:"100px"}).

target : Object

[READ-ONLY] Target object (or array of objects) whose properties the tween affects.

ticker : Object

[static] The object that dispatches a "tick" event each time the engine updates, making it easy for you to add your own listener(s) to run custom logic after each update (great for game developers).

Methods

delayedCall( delay:Number, callback:Function, params:Array, scope:*, useFrames:Boolean ) : TweenMax

[static] Provides a simple way to call a function after a set amount of time (or frames).

from( target:Object, duration:Number, vars:Object ) : TweenMax

[static] Static method for creating a TweenMax instance that tweens backwards - you define the BEGINNING values and the current values are used as the destination values which is great for doing things like animating objects onto the screen because you can set them up initially the way you want them to look at the end of the tween and then animate in from elsewhere.

fromTo( target:Object, duration:Number, fromVars:Object, toVars:Object ) : TweenMax

[static] Static method for creating a TweenMax instance that allows you to define both the starting and ending values (as opposed to to() and from() tweens which are based on the target's current values at one end or the other).

getAllTweens( includeTimelines:Boolean ) : Array

[static] Returns an array containing all tweens (and optionally timelines too, excluding the root timelines).

getTweensOf( target:Object, onlyActive:Boolean ) :

[static] Returns an array containing all the tweens of a particular target (or group of targets) that have not been released for garbage collection yet which typically happens within a few seconds after the tween completes.

globalTimeScale( value:Number ) :

[static] Gets or sets the global timeScale which is a multiplier that affects ALL animations equally. This is a great way to globally speed up or slow down all animations at once.

invalidate( ) : *

[override] Clears any initialization data (like starting/ending values in tweens) which can be useful if, for example, you want to restart a tween without reverting to any previously recorded starting values.

isTweening( target:Object ) : Boolean

[static] Reports whether or not a particular object is actively tweening.

killAll( complete:Boolean, tweens:Boolean, delayedCalls:Boolean, timelines:Boolean ) :

[static] Kills all tweens and/or delayedCalls/callbacks, and/or timelines, optionally forcing them to completion first.

killChildTweensOf( parent:Object, complete:Boolean ) :

[static] Kills all tweens of the children of a particular DOM element, optionally forcing them to completion first.

killDelayedCallsTo( function:Function ) :

[static] Immediately kills all of the delayedCalls to a particular function.

killTweensOf( target:Object, vars:Object ) :

[static] Kills all the tweens (or specific tweening properties) of a particular object or the delayedCalls to a particular function.

lagSmoothing( threshold:Number, adjustedLag:Number ) :

Permits you to control what happens when too much time elapses between two ticks (updates) of the engine, adjusting the core timing mechanism to compensate and avoid "jumps".

pauseAll( tweens:Boolean, delayedCalls:Boolean, timelines:Boolean ) :

[static] [deprecated] Pauses all tweens and/or delayedCalls/callbacks and/or timelines.

progress( value:Number, suppressEvents:Boolean ) : *

[override] Gets or sets the tween's progress which is a value between 0 and 1 indicating the position of the virtual playhead (excluding repeats) where 0 is at the beginning, 0.5 is halfway complete, and 1 is complete.

render( ) :

Forces a render of all active tweens which can be useful if, for example, you set up a bunch of from() tweens and then you need to force an immediate render (even of "lazy" tweens) to avoid a brief delay before things render on the very next tick.

repeat( value:Number ) : *

Gets or sets the number of times that the tween should repeat after its first iteration.

repeatDelay( value:Number ) : *

Gets or sets the amount of time in seconds (or frames for frames-based tweens) between repeats.

resumeAll( tweens:Boolean, delayedCalls:Boolean, timelines:Boolean ) :

[static] [deprecated] Resumes all paused tweens and/or delayedCalls/callbacks and/or timelines.

set( target:Object, vars:Object ) : TweenMax

[static] Immediately sets properties of the target accordingly - essentially a zero-duration to() tween with a more intuitive name.

staggerFrom( targets:Array, duration:Number, vars:Object, stagger:Number, 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.

staggerFromTo( targets:Array, duration:Number, fromVars:Object, toVars:Object, stagger:Number, onCompleteAll:Function, onCompleteAllParams:Array, onCompleteAllScope:* ) : Array

[static] Tweens an array of targets from a common set of destination values 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.

staggerTo( targets:Array, duration:Number, vars:Object, stagger:Number, onCompleteAll:Function, onCompleteAllParams:Array, onCompleteAllScope:* ) : Array

[static] 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.

time( value:Number, suppressEvents:Boolean ) : *

[override] Gets or sets the local position of the playhead (essentially the current time), not including any repeats or repeatDelays.

to( target:Object, duration:Number, vars:Object ) : TweenMax

[static] Static method for creating a TweenMax instance that animates to the specified destination values (from the current values).

totalDuration( value:Number ) : *

[override] Gets or sets the total duration of the tween in seconds (or frames for frames-based tweens) including any repeats or repeatDelays.

totalProgress( value:Number, suppressEvents:Boolean ) : *

totalProgress()

updateTo( vars:object, resetDuration:Boolean ) : *

Updates tweening values on the fly so that they appear to seamlessly change course even if the tween is in-progress.

yoyo( value:Boolean ) : *

Gets or sets the tween's yoyo state, where true causes the tween to go back and forth, alternating backward and forward on each repeat.

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.

Get GSAP

Version: 1.20.3 updated 2017-10-02

Core

    Extras

      Plugins

        By using GreenSock code, you agree to the terms of use.

        Help support GreenSock by becoming a member

        Join Club GreenSock