Getting Started with the JavaScript Version of the GreenSock Animation Platform (GSAP)

Quick links:

• Introduction
• Loading the file(s)
• Basic tweening
• Special properties
• Easing
• Plugins
• Tweening CSS properties
• Controlling tweens
• Sequencing and grouping tweens with TimelineLite
• Stepping up to TweenMax and TimelineMax
• Overwriting other tweens
• FAQ

t

t

Note: this document applies to version 1.9.0 or later of TweenLite (and TweenMax). Please make sure you update your files if you’re using an older version.

Jump Start

If you haven’t done so already, please check out the Jump Start for GSAP JS – it visually demonstrates the basics of the API and gets you up and running fast. The interactive slides make it easy (or dare we say it…”fun!”). Then, if you’re still hungry for more, circle back here because this page goes into a bit more detail. The Jump Start is the best place to begin learning.

Introduction

Animating with code may seem intimidating at first, but don’t worry – the GreenSock Animation Platform (GSAP) was engineered to make it simple and intuitive. The platform is also highly optimized for performance and unprecedented flexibility. Hang in there through the learning curve and you’ll be glad you did. For now, we’ll focus on getting you up and running with the core engine, TweenLite. Then we’ll discuss if (and when) you might want to put the other tools to work (like TweenMax, TimelineLite, TimelineMax, etc.). If you’ve used the Flash version of the platform, you should notice that the syntax is identical (although you’ll definitely want to read up on the CSSPlugin and check out the FAQ section below).

What exactly is GSAP?

The GreenSock Animation Platform is a suite of tools for scripted animation. It includes:

• TweenLite: the core of the engine which handles animating just about any property of any object. It is relatively lightweight yet full-featured and can be expanded using optional plugins (like CSSPlugin for animating DOM element styles in the browser, or ScrollToPlugin scrolling to a specific location on a page or div, etc.)
• TweenMax: TweenLite’s beefy big brother; it does everything TweenLite can do plus non-essentials like repeat, yoyo, repeatDelay, etc. It includes many common plugins too like CSSPlugin so that you don’t need to load as many files. The focus is on being full-featured rather than lightweight.
• TimelineLite: a powerful, lightweight sequencing tool that acts like a container for tweens, making it simple to control them as a whole and precisely manage their timing in relation to each other. You can even nest timelines inside other timelines as deeply as you want. This allows you to modularize your animation workflow easily.
• TimelineMax: extends TimelineLite, offering exactly the same functionality plus useful (but non-essential) features like repeat, repeatDelay, yoyo, currentLabel(), and many more. Again, just like TweenMax does for TweenLite, TimelineMax aims to be the ultimate full-featured tool rather than lightweight.
• Extras like easing tools, plugins, and more

Loading the GSAP files

Check out the download screen where you can download a zip containing minified and uncompressed files, or you can just paste a CDN link right into your page. The simplest way to get a bunch of goodies is to link to the latest TweenMax CDN file.

<script src="http://cdnjs.cloudflare.com/ajax/libs/gsap/latest/TweenMax.min.js"></script>

Since TweenMax includes TweenLite, CSSPlugin, EasePack, TimelineLite, TimelineMax, RoundPropsPlugin, BezierPlugin, AttrPlugin, and DirectionalRotationPlugin, this one file gives you tons of goodies to play with and the CDN should help things load very quickly. If, however, you’re more concerned about file size, you can pick and choose which core components and plugins to load (a common lightweight choice is TweenLite, CSSPlugin, and EasePack). For example:

<script src="http://cdnjs.cloudflare.com/ajax/libs/gsap/latest/plugins/CSSPlugin.min.js"></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/gsap/latest/easing/EasePack.min.js"></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/gsap/latest/TweenLite.min.js"></script>

Notice that we’re linking to the “latest” version of these files, which means that as new versions come out you should automatically get those updates. Typically that’s a GOOD thing especially when bugs were discovered and squashed, but beware that there’s a chance that an update could potentially change behavior (either because of an inadvertent consequence of updated code in the engine or intentional feature/API changes), so you can link to specific versions in the CDN (like 1.9.0) if you prefer (see the download screen for details). Don’t worry – we’re VERY cautious about making changes that could affect legacy code. Sign up for a GreenSock account to join the mailing list and get notifications about important updates that could affect your code.

Of course you don’t need to use CDN links at all. If you download the zip, look inside the “src” folder and you’ll see “minified” and “uncompressed” folders with all the source code – feel free to drop those onto your server or local file system. You’ll typically want to use the minified files for deployment because they’ll load faster but functionally everything is identical between the uncompressed and minified versions. The “uncompressed” files are included just in case you want to crack open the source and see what’s happening in there (they contain comments and more human-readable code). You can also check out our Github repository.

If you don’t need to animate DOM element styles, you don’t need CSSPlugin. You can, for example, just use the very lightweight TweenLite to animate EaselJS objects on a canvas or RaphaelJS objects for SVG. And if you don’t need special easing equations beyond the standard ones (Power0, Power1, Power2, Power3, Power4, Linear, Quad, Cubic, Quart, Quint, and Strong are all included inside the TweenLite file), you can skip EasePack which adds Elastic, SlowMo, Bounce, SteppedEase, Sine, Circ, and Expo.

Don’t forget to load the JavaScript file(s) BEFORE any of your animation code (otherwise when the browser gets to your animation code, it won’t know what “TweenMax” or “TweenLite” is since it hasn’t loaded yet).

We strongly recommend that you keep your GSAP files updated because we’re actively enhancing features, working around browser bugs/inconsistencies, etc. Swing by the site once in a while and snag the latest files.

Looking for a jQuery plugin?

GSAP has no dependencies on jQuery, but if you’re used to the jQuery.animate() method or you have an existing project that makes extensive use of it and you’d prefer to get the speed benefits of GSAP under the hood (plus all the extra tweenable properties like 3D transforms, colors, boxShadow, etc.), the jquery.gsap plugin is perfect for you. It basically hijacks the regular jQuery.animate() method and makes GSAP drive the animations under the hood. We’d recommend shifting to the regular GSAP tools/API eventually rather than the jquery.gsap plugin because you’ll get a lot more flexibility and power with its object-oriented nature, but the jQuery plugin can be a great way to add some GSAP juice to your jQuery project with almost zero effort. Get details about the plugin here.

Basic tweening

TweenLite can tween ANY numeric property of ANY JavaScript object, not just a predetermined list of properties of certain object types. For example, we could create a generic object and assign an arbitrary property and then tween it from 0 to 100 over 2 seconds like this:

var obj = {myProp:0};
TweenLite.to(obj, 2, {myProp:100});

The first parameter we feed the tween is the target (the object whose properties you want to tween), the second is the duration (typically in seconds), and the last is an object with one or more properties that should be tweened to the provided end values. Let’s say, for example, you have an <img> with an id of “photo” and you’d like to tween its “width” property to a value of 100 over the course of 1.5 seconds. You can use TweenLite’s to() method:

var photo = document.getElementById("photo"); //or use jQuery's $("#photo")
TweenLite.to(photo, 1.5, {width:100});

Since this is a to() tween, the “width” property is tweened to 100 from whatever it happens to be at the time the tween begins. If you want to also tween the “height” property to 200 simultaneously, you’d do:

TweenLite.to(photo, 1.5, {width:100, height:200});

There is no limit to the number of properties you can tween. And the order in which they are defined doesn’t matter.

Notice we used document.getElementById() above to get the “photo” element so that we can tween it. Wouldn’t it be nice if you could just pass that string to TweenLite/Max and have it find it for you? Of course. As of version 1.8.0, GSAP treats string targets as selector text and feeds it to the selector engine of your choice. It will look for window.$ and then window.jQuery and if neither is found, it will default to document.getElementById() (in which case it will also strip out any leading “#” in any IDs it receives). Feel free to use any selector you want: jQuery, Zepto, Sizzle, or your own. Set it like this: TweenLite.selector = YOUR_SELECTOR_ENGINE;

If jQuery is loaded (or anything that’s defined as the industry standard window.$), you don’t need to do anything – GSAP will automatically sense (and use) it. But GSAP does NOT have any dependencies on jQuery or any specific selector engine.

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

Defining the target as a string of selector text is simply a convenience – it’s completely optional. Ultimately the target must be an object anyway, so you can define it as such up front. Pass in a jQuery object or an array or an HTML element or a generic object as the target.

There is a very useful from() method that allows you to essentially go in reverse, defining the starting values and tweening to the current values. This makes it easy to animate things into place. For example:

//animate from 0 to whatever the scaleX/scaleY is now
TweenLite.from(photo, 1.5, {scaleX:0, scaleY:0});

There is also a fromTo() method that allows you to define the starting values and the ending values:

//tweens from width 0 to 100 and height 0 to 200
TweenLite.fromTo(photo, 1.5, {width:0, height:0}, {width:100, height:200});

If you prefer a more object-oriented approach and/or would like to store references to your tweens in variables so that you can control them later (for example, pause(), resume(), reverse(), restart()), you can create a tween like this (which is identical to a to() tween):

var myTween = new TweenLite(photo, 1.5, {width:100, height:200});

By default, all tweens play immediately, but you can pause them initially by passing paused:true in the vars parameter or by calling pause() on the instance.

//pause the tween initially
var myTween = TweenLite.to(photo, 1.5, {width:100, paused:true});

//then later, resume
myTween.resume();

Special properties

A special property is a reserved keyword that TweenLite recognizes and handles differently than it would a normal property. One example is “delay” which allows you to delay a tween’s start time by a certain number of seconds.

//waits 2 seconds before beginning ("delay" is a special property TweenLite recognizes)
TweenLite.to(photo, 1.5, {width:100, delay:2});

TweenLite recognizes several special properties that are quite useful, like onComplete, ease, overwrite, paused, useFrames, immediateRender, onStart, onUpdate, onCompleteParams, and more. Please read the full documentation for details. Two of the most common special properties are “ease” and “onComplete”. We’ll talk about “ease” later, but onComplete gives you a way to call a function when the tween completes (commonly known as a “callback”), making it simple to create a chain of actions.

Here is a tween that delays its start time by 0.5 seconds, and calls myFunction() when it completes:

//notice there's no "()" after the onComplete function because it's just a reference to the function itself (you don't want to call it yet)
TweenLite.to(photo, 1.5, {width:100, delay:0.5, onComplete:myFunction});
function myFunction() {
    console.log("tween finished");
}

Easing

An “ease” alters the rate of change during a tween. This essentially gives the movement a different “feel”. There are many to choose from and the best way to understand the various options is to experiment with them. Below is an interactive tool that allows you to select an ease and a duration and then click the “start” button to see the green box animate across the screen with the selected ease.

The default ease in TweenLite is Power1.easeOut (which gives a more natural feel than a linear ease). Here is the syntax for defining the ease for a few tweens:

TweenLite.to(photo, 1, {width:100, ease:Power2.easeOut});
TweenLite.to(photo, 1, {height:200, ease:Elastic.easeOut});

If you prefer, you can define the ease as a string instead, either in the normal format like “Elastic.easeOut” or in the reverse no-dot synax (jQuery-style) like “easeOutElastic”.

TweenLite.to(photo, 1, {width:100, ease:"Elastic.easeOut"});
TweenLite.to(photo, 1, {height:200, ease:"easeOutElastic"});

To get linear motion, just use the Linear.easeNone ease. Frankly, the most useful eases are all the Power eases, Back.easeOut, Elastic.easeOut, SlowMo.ease, Bounce.easeOut and sometimes Linear.easeNone. The rest are more for legacy code and they don’t look much different than one of the Power eases. The Power eases are all baked into the TweenLite core so that they’re accelerated in terms of performance.

Plugins

Think of plugins like special properties that are dynamically added to TweenLite, giving it extra abilities. This keeps the core engine small and efficient, yet allows for virtually unlimited capabilities to be added dynamically. 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 loaded, it will intercept the “css” property, and the ScrollToPlugin will intercept the “scrollTo” value, etc.:

//CSSPlugin will intercept the "css" value...
TweenLite.to(photo, 1, {css:{scaleX:0.5, rotation:30}, ease:Power3.easeOut});

//ScrollToPlugin will intercept the "scrollTo" value (if it's loaded)...
TweenLite.to(window, 2, {scrollTo:{y:300}, ease:Bounce.easeOut});

Normally, css-specific properties would need to be wrapped in their own object and passed in like TweenLite.to(element, 1, {css:{left:"100px", top:"50px"}}); so that the engine knows that those properties should be handled by CSSPlugin, but because animating DOM elements in the browser is so common, TweenLite and TweenMax (as of version 1.8.0) automatically check to see if the target is a DOM element and if it is (and you haven’t already defined a “css” object in the vars parameter), the engine creates that css object for you and shifts any properties that aren’t reserved (like onComplete, ease, delay, etc. or plugin keywords like scrollTo, raphael, easel, etc.) into that css object when the tween renders for the first time. There is a slight performance penalty (virtually imperceptible unless you’re tweening a LOT of elements simultaneously), but in most cases the convenience is well worth it. In the code examples below, we’ll use the more concise style that omits the css:{} object but be aware that either style is acceptable.

//as of 1.8.0 the following two lines produce identical results, but the first instantiates slightly faster. The 2nd is more convenient to write, though.
TweenLite.to(element, 1, {css:{top:"20px", backgroundColor:"#FF0000"}, ease:Power2.easeOut});
TweenLite.to(element, 1, {top:"20px", backgroundColor:"#FF0000", ease:Power2.easeOut});

Don’t forget that you need to load the plugin’s JavaScript file to ensure that it works. For convenience, the major plugins like CSSPlugin, RoundPropsPlugin, and BezierPlugin are included inside of the TweenMax JavaScript file.

Tweening CSS properties

With the help of the CSSPlugin, GSAP can animate almost any css-related property of DOM elements including the obvious things like width, height, margins, padding, top, left, and more plus complex properties like transforms (rotation, scaleX, scaleY, skewX, skewY, x, y, rotationX, and rotationY), colors, backgroundPosition, opacity, and lots more. Load the CSSPlugin js file to enable these capabilities.

Note: a common mistake is to forget to use camel case representations of the properties, so instead of “font-size”, you’d use “fontSize”. “background-color” would be “backgroundColor”.

You can even define properties that are not generally tweenable and GSAP will apply the property for you (like position:”absolute” or borderStyle:”solid”). It is typically a good idea to define a unit of measurement (like “24px” instead of “24″ or “50%” rather than “50″) but the default in most cases is pixels (px), so you can omit the unit if you prefer. And even if the unit of measurement doesn’t match the current one, GSAP will attempt to convert them for you. So, for example, you could tween a width from “50%” to “200px”.

CSSPlugin can even animate complex values like boxShadow:"0px 0px 20px 20px red" and borderRadius:"50% 50%" and border:"5px solid rgb(0,255,0)". When necessary, it attempts to figure out if the property needs a vendor prefix and applies it accordingly. There may be a small subset of complex or bleeding-edge css properties that CSSPlugin can’t handle yet, but the vast majority work great.

In addition to almost all of the standard css properties, CSSPlugin recognizes some special ones that can be quite convenient:

• 2D transforms like rotation, scaleX, scaleY, scale, skewX, skewY, x, and y – one of the most convenient things about the CSSPlugin is that it greatly simplifies transforms in the various browsers including IE back through version 6! No need to mess with various browser prefixes and funky matrix filters in IE. You can just set transform properties inuitively.

  //much simpler
  TweenLite.to(element, 2, {rotation:30, scaleX:0.8});

  By default, rotation, skewX, and skewY use degrees but you can use radians if you prefer. Simply append one of the standard suffixes (“rad” or “deg”) like this:

  //use "deg" or "rad"
  TweenLite.to(element, 2, {rotation:"1.25rad", skewX:"30deg"});

  To be clear, this is like setting the element’s css transform:rotate(1.25rad) skewX(30deg) along with all the other browser prefix values and IE filter which would be much more verbose.

  Notes about 2D transforms:
  1. It is typically best to set the element’s position to “absolute” to avoid clipping (mostly for old versions of IE).
  2. You can use “scale” as a shortcut to control both the “scaleX” and “scaleY” properties identically.
  3. The order in which you declare the transform properties makes no difference.
  4. TweenLite has nothing to do with the rendering quality of the element in the browser. Some browsers seem to render transformed elements beautifully while others don’t handle anti-aliasing as well.
• 3D transforms: in addition to all of the regular 2D properties (x, y, scaleX, scaleY, scale, rotation, skewX, and skewY) that work in almost all browsers, you can animate 3D properties too like rotationX, rotationY, rotationZ (identical to regular “rotation”), z, perspective, and transformPerspective in most modern browsers (see http://caniuse.com/transforms3d for details about browser support for 3D transforms). Again, there is no need to use browser prefixes; CSSPlugin handles all of that for you under the hood. You can animate 3D transform properties and 2D properties (except skew) together inuitively:

  TweenLite.to(element, 2, {rotationX:45, scaleX:0.8, z:-300});
  

  See some interactive examples of 3D transforms and other CSS3 property animations like boxShadow, textShadow, borderRadius, and clip in this article. It demonstrates perspective principles too.

  To get your elements to have a true 3D visual perspective applied, you must either set the “perspective” property of the parent element or set the special “transformPerspective” of the element itself (common values range from around 200 to 1000, the lower the number the stronger the perspective distortion). The “transformPerspective” is like adding a perspective() directly inside the css “transform” style, like: transform:perspective(500px) rotateX(45deg) which only applies to that specific element whereas if you want to a group of elements share a common perspective (the same vanishing point), you should set the regular “perspective” property on the parent/container of those elements. For more information about perspective, see this article.

  //apply a perspective to the PARENT element (the container) to make the perspective apply to all child elements (typically best)
  TweenLite.set(container, {perspective:500});
  
  //or set a default perspective that will be applied to every individual element that you tween in 3D:
  CSSPlugin.defaultTransformPerspective = 500;
  
  //or apply perspective to a single element using "transformPerspective"
  TweenLite.set(element, {transformPerspective:500});
  

  In regular CSS, the order that you list the transforms matters but GSAP always applies them in the same order for consistency: scale, then rotation (same as rotationZ), then rotationY, then rotationX, then translation (x, y, z). If you want to rotate the element around a point in 3D space other than its center, use the transformOrigin property (see below).

  //sample css:
  .myClass {
      transform: scale(1.5, 1.5) rotateY(45deg) translate3d(10px, 0px, -200px)
  }
   
  //corresponding GSAP transform (tweened over 2 seconds):
  TweenLite.to(element, 2, {scale:1.5, rotationY:45, x:10, y:0, z:-200});
  
  //sample css that uses a perspective():
  .myClass {
      transform: perspective(500px) rotate(120deg) translateY(50px)
  }
  
  //corresponding GSAP transform (set, not tweened):
  TweenLite.set(element, {transformPerspective:500, rotation:120, y:50});
  

  Notes about 3D transforms:

  1. In browsers that don’t support 3D transforms, they’ll be ignored. For example, rotationX may not work, but rotation would. See http://caniuse.com/transforms3d for a chart of which browser versions support 3D transforms.
  2. All transforms are remembered, so you can tween individual properties without worrying that they’ll be lost. You don’t need to define all of the transform properties on every tween – only the ones you want to animate.
  3. TweenLite has nothing to do with the rendering quality of the element in the browser. Some browsers seem to render transformed elements beautifully while others don’t handle anti-aliasing as well.
  4. To learn more about css 3D transforms, see this article
     
• transformOrigin – Sets the origin around which all transforms occur. By default, it is in the center of the element ("50% 50%"). You can define the values using the keywords "top", "left", "right", or "bottom" or you can use percentages (bottom right corner would be "100% 100%") or pixels. If, for example, you want an object to spin around its top left corner you can do this:

  //spins around the element's top left corner
  TweenLite.to(element, 2, {rotation:360, transformOrigin:"left top"});

  The first value in the quotes refers to the x-axis and the second refers to the y-axis (you can optionally add a 3rd value to define a point in 3D space), so to make the object transform around exactly 50px in from its left edge and 20px from its top edge, you could do:

  //spins/scales around a point offset from the top left by 50px, 20px
  TweenLite.to(element, 2, {rotation:270, scale:0.5, transformOrigin:"50px 20px"});

• directionalRotation – tweens rotation in a particular direction which can be either clockwise ("_cw" suffix), counter-clockwise ("_ccw" suffix), or in the shortest direction ("_short" suffix) in which case the plugin chooses the direction for you based on the shortest path. For example, if the element’s rotation is currently 170 degrees and you want to tween it to -170 degrees, a normal rotation tween would travel a total of 340 degrees in the counter-clockwise direction, but if you use the “_short” suffix, it would travel 20 degrees in the clockwise direction instead. Example:

  TweenLite.to(element, 2, {rotation:"-170_short"});
  
  //or even use it on 3D rotations and use relative prefixes:
  TweenLite.to(element, 2, {rotation:"-170_short", rotationX:"-=30_cw", rotationY:"1.5rad_ccw"});

  Prior to version 1.9.0, directionalRotation was called shortRotation and it only handled going in the shortest direction. The new directionalRotation functionality is much more flexible and easy to use (just slap a suffix on the regular property). For backwards compatibility, CSSPlugin still recognizes “shortRotation”, but it has been deprecated.

• autoAlpha – the same thing as "opacity" except that when the value hits "0", the "visibility" property will be set to "hidden" in order to improve browser rendering performance and prevent clicks/interactivity on the target. When the value is anything other than 0, "visibility" will be set to "visible". Example:

  //fade out and set visibility:hidden
  TweenLite.to(element, 2, {autoAlpha:0});
  
  //in 2 seconds, fade back in with visibility:visible
  TweenLite.to(element, 2, {autoAlpha:1, delay:2});

• className – allows you to morph between classes on an element. For example, let’s say myElement has a class of "class1" currently and you want to change to "class2" and animate the differences, you could do this:

  TweenLite.to(myElement, 1, {className:"class2"});

  And if you want to ADD the class to the existing one, you can simply use the “+=” prefix. To remove a class, use the “-=” prefix like this:

  TweenLite.to(myElement, 1, {className:"+=class2"});

  Note: there are a few css-related properties that don’t tween like IE filters, but that is a very rare exception. Also, there is a slight speed penalty when using className because the engine needs to loop through all of the css properties to analyze which ones are different.

• autoRound – By default, CSSPlugin will round pixel values and zIndex to the closest integer during the tween (the inbetween values) because it improves browser performance, but if you’d rather disable that behavior, pass autoRound:false in the css object. You can still use the RoundPropsPlugin to manually define properties that you want rounded.

Controlling tweens

Most other animation tools offer very limited controls, but GSAP was built from the ground up to be a professional-grade robust set of animation tools. You can easily pause(), resume() reverse(), restart(), seek(), or even alter the timeScale of any tween. In fact, you can tween the timeScale of another tween to gradually slow it down or speed it up. To control a tween, however, you need an instance to work with. The to(), from(), and fromTo() methods all return an instance, so you can dump it into a variable as easily as:

//using the static to() method...
var tween = TweenLite.to(element, 1, {width:"50%"});

//or use the object-oriented syntax...
var tween = new TweenLite(element, 1, {width:"50%"});

Then, you can call any of its methods:

//pause
tween.pause();

//resume (honors direction - reversed or not)
tween.resume();

//reverse (always goes back towards the beginning)
tween.reverse();

//jump to exactly 0.5 seconds into the tween
tween.seek(0.5);

//make the tween go half-speed
tween.timeScale(0.5);

//make the tween go double-speed
tween.timeScale(2);

//immediately kill the tween and make it eligible for garbage collection
tween.kill();

You can also kill ALL of the tweens of a particular element/target like this:

TweenLite.killTweensOf(myElement);

See the full documentation for details about all of the properties and methods available.

Sequencing and grouping tweens with TimelineLite

Unlike most other JS animation tools, sequencing in GSAP is much more flexible than building a queue of tweens that run one-after-the-other. You have complete control over the relative timing of each tween – they can overlap as much as you want. And you can control entire sequences as a whole, reverse smoothly anytime, jump to any point, adjust the timeScale, etc. and everything renders in the proper order.

Watch this video for a visual demo showing how TimelineLite can save you a lot of time.

Of course you could sequence tweens by using the “delay” special property on all your tweens, but that can get complicated when you build a long sequence and then later want to change the timing of something early in the sequence (you’d have to adjust all the delay values in tweens after that). Plus it would be a pain to control the whole sequence, like to pause() or resume() or reverse() the group on-the-fly. Sequencing is much easier with TimelineLite and its big brother, TimelineMax.

Let’s jump into some sample code:

//create a TimelineLite instance
var tl = new TimelineLite();

//append a to() tween
tl.to(element, 1, {width:"50%"});

//add another sequenced tween (by default, tweens are added to the end of the timeline which makes sequencing simple)
tl.to(element, 1, {height:"300px", ease:Elastic.easeOut});

//offset the next tween by 0.75 seconds so there's a gap between the end of the previous tween and this new one
tl.to(element, 1, {opacity:0.5}, "+=0.75");

//overlap the next tween with the previous one by 0.5 seconds (notice the negative offset at the end)
tl.to(element, 1, {backgroundColor:"#FF0000"}, "-=0.5");

//animate 3 elements (e1, e2, and e3) to a rotation of 60 degrees, and stagger their start times by 0.2 seconds
tl.staggerTo([e1, e2, e3], 1, {rotation:60}, 0.2);

//then call myFunction()
tl.call(myFunction);

//now we can control the entire sequence with the standard methods like these:
tl.pause();
tl.resume();
tl.restart();
tl.reverse();
tl.play();

//jump to exactly 2.5 seconds into the animation
tl.seek(2.5);

//slow down playback to 10% of the normal speed
tl.timeScale(0.1);

//add a label named "myLabel" at exactly 3 seconds:
tl.add("myLabel", 3);

//add a tween that starts at "myLabel"
tl.add( TweenLite.to(element, 1, {scale:0.5}), "myLabel");

//jump to "myLabel" and play from there:
tl.play("myLabel");

Think of a timeline (as in a TimelineLite or TimelineMax instance) like a collection of tweens that are positioned at specific places on that timeline. It controls their playback. Timelines can be nested inside other timelines as deeply as you want. This is a very powerful concept because it allows you to control entire sequences in a modular way. Imagine 100 characters individually animating into place in a staggered fashion (100 tweens). They could all be grouped into a TimelineLite instance and then controled as a whole (using common methods like pause(), resume(), reverse(), restart(), etc.). In fact, you could create functions that return animations wrapped in a TimelineLite so that you can easily build a larger, more complex animation in a modular way.

A central concept to grasp is that every tween is inserted into a timeline. By default, it’s the root timeline inside the engine. When a timeline is playing, its virtual playhead advances. If you reverse() a timeline, the playhead travels in the opposite direction back towards its beginning. As the timeline’s playhead encounters tweens, it plays them accordingly. For example, if the playhead is positioned halfway through a tween, that tween will render as though it is 50% finished. If the timeline’s timeScale is set to 0.5, that would cause the playhead to travel at half speed. Consequently, any tweens it encounters would also appear to progress at half speed. Once you get the hang of how timelines work, they can revolutionize your animation workflow.

Just like tweens, timelines play immediately by default but you can pause them initially using pause() or by setting paused:true in the vars parameter of the constructor.

There are quite a few methods available in the timeline classes that give you precise control, and we’d encourage you to look through the full documentation to see what’s available. If you can think of something you’d like to do, chances are there’s a way to do it.

Stepping up to TweenMax and TimelineMax

Tight file size, outstanding performance, and a relatively robust feature set were all priorities in TweenLite and TimelineLite but there were some extra features that we wanted to add without bloating the core components. Enter TweenMax and TimelineMax. TweenMax extends TweenLite, doing EVERYTHING it does plus extras like repeat, yoyo, repeatDelay, and more. TimelineMax does the same for TimelineLite. Plus when you load the TweenMax JavaScript file, it also includes a bunch of extras automatically like CSSPlugin, RoundPropsPlugin, BezierPlugin, AttrPlugin, DirectionalRotationPlugin, TimelineLite, TimelineMax, and EasePack. Basically, if file size is a major concern for you, stick with TweenLite and manually load whichever plugins or eases you need. Otherwise, use TweenMax because it delivers the ultimate feature set with minimal hassle.

TweenMax uses exactly the same syntax as TweenLite. In fact, a TweenMax instance is a TweenLite instance. If you have a project that already uses TweenLite you could literally do a search and replace for all “TweenLite” instances with “TweenMax” and it would work great. TweenMax just recognizes some extra special properties, for example:

//repeat this tween 3 times (for a total of 4 cycles) and wait 0.5 seconds between each repeat
TweenMax.to(element, 1, {width:"50%", repeat:3, repeatDelay:0.5});

//fade the opacity up and down infinitely (a repeat of -1 means infinitely)
TweenMax.to(element, 1, {opacity:0, repeat:-1, yoyo:true});

TimelineMax also offers repeat, yoyo, and repeatDelay as well as convenient methods like tweenTo(), currentLabel(), getLabelBefore() and getLabelAfter() and more.

var tl = new TimelineMax({repeat:3, yoyo:true, repeatDelay:1, onComplete:timelineDone, onCompleteParams:["test1", "test2"]});
tl.staggerTo([e1, e2, e3], 1, {opacity:0, rotation:360}, 0.2);
function timelineDone(p1, p2) {
    console.log("timeline done. params: " + p1 + " and " + p2);
}

Overwriting other tweens

An often overlooked aspect of tweening is how (and if and when) tweens overwrite other tweens of the same object. For example, let’s say you have a button with onmouseover and onmouseout handlers that tween its opacity higher on the “over” event and lower on “out” event. To further complicate things, let’s say the “over” tween lasts 2 seconds and the “out” tween lasts 1 second. What should happen if the user rolls over/out/over/out quickly? See the problem? If tweens are allowed to run without any kind of overwriting, they’ll build up and fight with each other (one trying to tween the opacity higher, and the other lower). In this example, when the user rolls over, a 2-second tween would start increasing the opacity to 1, but if the user rolled off 0.2 seconds later, another tween would begin, causing the opacity to decrease. When that tween finishes 1 second later, the “over” tween is still going (since it had a duration of 2 seconds), so the opacity would suddenly jump up and finish off at a value of 1 even though the user rolled out!

Don’t worry. We’ve got you covered.

By default, whenever a TweenLite instance renders for the first time (after any delay), it analyzes all other active tweens of the same target and checks for individual overlapping properties. If it finds any, it kills the offending overlaps (again, only the individual properties). This overwrite mode is called "auto" and it is typically the most intuitive. However, there may be times when you want the new tween to kill all other tweens of the same object regardless of their start times or overlapping properties. That is what the "all" overwrite mode is for. And to skip overwriting altogether, you can define an overwrite mode of "none". There are several other modes to choose from too, so check out the full docs for details. You define an overwrite mode with the “overwrite” special property like this:

//overwrites all tweens of myElement immediately
TweenLite.to(myElement, 1, {width:"50%", overwrite:"all"});

//doesn't overwrite anything (allows conflicts)
TweenLite.to(myElement, 1, {width:"50%", overwrite:"none"});

//overwrites only individual overlapping properties on concurrent tweens of myElement (this is the default, so you typically don't need to specify any overwrite in this scenario)
TweenLite.to(myElement, 1, {width:"50%", overwrite:"auto"});

//set the default overwrite mode to "all" instead of "auto"
TweenLite.defaultOverwrite = "all";

Of course you can manually kill all the tweens of a particular object using the TweenLite.killTweensOf() method, but the nice thing about defining overwrite modes is that the overwriting doesn’t kick in until it’s necessary (when the tween renders for the first time) which is essential when working with complex sequences.

FAQ (click to view answer)

1. Can I use jQuery with the GreenSock tools?
   Absolutely! In fact, we encourage it. jQuery is great for selecting DOM elements, adding event handlers, and lots more. GSAP treats jQuery objects as arrays, so you can pass a single jQuery object as the target of the tween and TweenLite/Max will tween all of the elements therein. For example:

   //fade out all of the elements with the class "myClass"
   TweenLite.to(".myClass", 1, {opacity:0});
   
   //tween the width of the element with id "myElement" to 500px
   TweenLite.to("#myElement", 1, {width:"500px", ease:Elastic.easeOut});
   
   //tween the "marginTop" of all objects of the class "myClass" in a staggered fashion so that they appear to fall into place from 100px up
   var tl = new TimelineLite();
   tl.staggerFrom(".myClass", 1, {marginTop:"-=100px", opacity:0}, 0.1);
   
   //or use jQuery's each() method to loop through the results and stagger a fade out
   $(".myClass").each( function(index, element) {
       TweenLite.to( element, 1, {autoAlpha:0, delay:index * 0.2});
   });
   
   //add a click handler that uses $(this) to refer to the menu element that was clicked and tween its height to 100px
   $("#menu").click(
        function(){
   		TweenLite.to( $(this), 0.7, { height:"100px", ease:Power2.easeInOut } );
        }
   );
   

   Of course you need to load jQuery into your HTML document in order to use it. TweenLite doesn’t have any dependencies on 3rd party tools like jQuery, so it is completely optional.

2. Which browsers work with the JavaScript version of GSAP?
   GSAP itself is pure JavaScript and should work in virtually ALL browsers. The CSSPlugin tweens css-related values and its compatibility is based on which properties you use in your tweens. GSAP wasn’t intended to solve all browser incompatibilities, but it does implement wizardry for critical features like opacity, transforms (rotation, scaleX, scaleY, skewX, skewY, x, and y), and transformOrigin so those should work in all major browsers even back to IE6. Firefox doesn’t support backgroundPositionX or backgroundPositionY, so those specific properties won’t work but backgroundPosition will for virtually all browsers. There is NOT a predetermined list of css properties that you can tween – the platform will attempt to tween ANY property you pass in. If it is numeric, it will tween it. If it isn’t numeric and it isn’t a recognized special property, CSSPlugin will just set the property to the value you provide (without tweening it). So, for example, if you try to tween to display:"inline", that isn’t a tweenable property but it will still be set accordingly during the tween, so feel free to use that to your advantage.
3. How big are the JavaScript files?
   Here are the minified gzipped file sizes:

   • TweenLite (includes standard eases): 6.9kb (20.4kb without gzip)
   • CSSPlugin: 10.6kb (26.5kb without gzip)
   • RoundPropsPlugin: 0.5kb (1kb without gzip)
   • BezierPlugin: 3.6kb (7.8kb without gzip)
   • EasePack: 1.2kb (3.6kb without gzip)
   • TimelineLite: 2.8kb (8.8kb without gzip)
   • TimelineMax (includes TimelineLite): 4.4kb (15.6kb without gzip)
   • TweenMax (includes ALL of the above): 27.1kb (81.7kb without gzip)
4. How can I define relative values for tweens?
   Simply add a “+=” or “-=” prefix to the value to make it relative. For example:

   //make myElement's width 100px more than what it is when the tween begins
   TweenLite.to(myElement, 1, {width:"+=100px"});
   
   //make myElement's rotation 30 degrees less than what it is when the tween starts
   TweenLite.to(myElement, 1, {rotation:"-=30deg"});

5. Does the CSSPlugin solve all of the browser inconsistencies or change the way css properties are rendered in the browser?
   It can’t solve all inconsistencies but it does solve a LOT of them and works around various bugs in the browsers. For example, it leverages IE’s filters and some fancy math with margins to make 2D transforms work in older versions of IE (including transformOrigin), plus opacity works across all major browsers (again, using filters in old versions of IE). Workarounds are included for Safari’s 3D transformOrigin bug and Firefox’s flickering 3D transforms issue and iOS’s requestAnimationFrame inconsistency, and many more.
6. Can I tween multiple objects with one tween?
   Sure, just pass an array of the objects as the target of the tween, like this:

   //tweens multiple objects simultaneously
   TweenLite.to([e1, e2, e3], 1, {autoAlpha:0});

7. Does it matter what order I define things inside the vars parameter?
   No, it doesn’t matter.

   //the following produce identical results (the order of the properties doesn't matter)
   TweenLite.to(element, 1, {width:"50%", height:"300px", ease:Power2.easeOut});
   TweenLite.to(element, 1, {height:"300px", width:"50%", ease:Power2.easeOut});
   TweenLite.to(element, 1, {ease:Power2.easeOut, width:"50%", height:"300px"});

8. Can I use GSAP for canvas objects or 3rd party tools like EaselJS? Is it only for animating DOM elements?
   You can animate ANY numeric property of ANY JavaScript object – it’s not just for DOM elements. So yes, you can animate canvas objects, EaselJS assets, and pretty much anything JavaScript-related. If you need to run logic after each refresh (like to redraw things on the canvas), either use an onUpdate on the individual tween/timeline or add a “tick” event listener to the core Ticker that drives the platform.
9. Does TweenLite/Max use CSS3 transitions to deliver even better performance (with help from the GPU)?
   Unfortunately CSS3 transitions have some significant limitations that make them unworkable for a serious animation platform. They don’t provide precise controls over the timing or easing. They’re great for simple effects but the GreenSock Animation Platform delivers extremely precise rendering, so you can do things like pause() and reverse() an animation anytime or skip to a specific time and play from there, etc. Try creating a CSS3 transition that uses an Elastic.easeOut or SlowMo.ease and then jump to 0.72494-seconds into a 2-second transition and pause() only to resume() later. It’s impossible from what I understand. So no, the platform doesn’t make use of CSS3 transitions. However, it is highly optimized for performance. See the CSS3 Transitions Cage Match for a detailed breakdown of how GSAP stacks up against “hardware accelerated” transitions.
10. What if i need to pass parameters to my onComplete function or define its scope?
    That’s what the onCompleteParams and onCompleteScope special properties are for. Here is some sample code:

    TweenLite.to(element, 1, {width:"50%", onComplete:myFunction, onCompleteParams:["param1", "param2"], onCompleteScope:this});
    function myFunction(p1, p2) {
    	console.log("tween completed. Received parameters: " + p1 + " and " + p2 + ". The scope is: " + this);
    }
    
    //or if you are using jQuery, here is an example of using $(this) to clarify scope. When you click the element with an id of "myElement", it will tween its height to 100px and then its width to 50%. Notice since we define the onCompleteScope, the "this" keyword inside the onComplete function refers to the element itself:
    $("#myElement").click(
         function(){
    		TweenLite.to($(this), 0.7, { height:"100px", ease:Power2.easeInOut, onCompleteScope:$(this), onComplete:function(){
    				TweenLite.to(this, 0.7, { width:"50%", ease:Power2.easeInOut} );
    			}
    		});
         }
    );

    The same is true for onUpdate, onUpdateParams, onUpdateScope, onStart, onStartParams, and onStartScope. See the full documentation for details.

11. Do I need to worry about garabage collection? What happens to a tween when it finishes?
    No need to worry. Tweens and timelines are automatically made eligible for garbage collection when appropriate (typically when they finish but if you maintain a reference to an instance so that you can restart it later, for example, it won’t be gc’d out from under you). In summary, the system manages this for you and generally cleans up after itself.
12. I noticed some occasional stutters and jerky animation – is that a problem with the animation engine?
    No, unforutunately most of the browsers have hiccups like that and they are indeed very annoying but they happen for any animation engine and really can’t be completely avoided (as far as I know). They most likely have to do with garbage collection routines which kick in unpredictably.
13. Does the GreenSock Animation Platform use the newer “requestAnimationFrame” API for its timing mechanism to maximize performance and minimize CPU load?
    Yes indeed, although it falls back to a standard setTimeout() if the browser doesn’t support requestAnimationFrame. And if you prefer not to use requestAnimationFrame, you can disable it by calling com.greensock.core.Animation.ticker.useRAF(false). The main benefit of requestAnimationFrame is that it synchronizes animation renders with when modern browsers refresh the screen and it also reduces the frequency of updates significantly when the user switches to another tab in the browser, reducing the load on the processor and saving battery on mobile devices.
14. Can I limit the number of frames per second that the tweening engine updates?
    Sure, you can set a maximum fps using the Ticker’s fps() method. For example to set it to 30fps, you’d do: TweenLite.ticker.fps(30). The default is roughly 60fps in most modern browsers.
15. Can I call my own function after every tick (frame), like for repainting a canvas or running my own game logic, etc.?
    Sure. You can use the Ticker’s addEventListener() to add your own “tick” event listener like this:

    TweenLite.ticker.addEventListener("tick", tickHandler);
    function tickHandler() {
    	//run your logic here...
    }

16. Can I chain the method calls like in jQuery?
    Most definitely. Here are some examples:

    //first we'll create a TimelineLite instance
    var tl = new TimelineLite();
    
    //now let's chain 3 sequenced tweens together
    tl.to(e1, 1, {autoAlpha:1}).to(e1, 2, {width:"50%", ease:Power2.easeInOut}).to(e1, 1, {height:"200px"});
    
    //or affect a tween immediately after it's created, like by setting its timeScale and jumping to a time of 0.5 and pausing there
    TweenLite.to(element, 5, {width:"500px"}).timeScale(2).pause(0.5);

17. What if I need to tween values that are attched to getter/setter functions rather than regular properties?
    No problem – TweenLite and TweenMax automatically sense if the property is a function and treat it accordingly. Let’s say, for example, you have an object with a “height()” method that acts as both a getter and setter (similar to many jQuery methods). Like if you pass a value it acts as a setter, otherwise it acts as a getter. Or maybe you have separate methods using the common naming convention with “get”/”set” prefixes like getMyProperty() and setMyProperty() – the platform handles both types of getters/setters easily:

    //first let's demonstrate using a common method for both getting and setting
    var h = obj1.height(); //gets
    obj1.height(100); //sets
    TweenLite.to(obj1, 1, {height:200}); //calls height() to get the initial value, and then sets the value on each update of the tween, passing the new value to height()
    
    //now we'll demonstrate using separate get/set methods
    var h = obj2.getHeight(); //gets
    obj2.setHeight(100); //sets
    TweenLite.to(obj2, 1, {setHeight:200}); //TweenLite automatically checks for an obj2.getHeight() to get the initial value, then uses obj2.setHeight() to set the height on each update of the tween.

18. Are more plugins coming? The Flash version seems to have a lot more than the JS version.
    Yes, you can expect to see more plugins coming in the future.
19. Do I have to purchase a license to use this code? Can I use it in commercial projects?
    GreenSock uses a very permissive license that allows you to use the tools for free for everything except a very specific type of commercial use (if you collect a fee from multiple customers for the same app/product/site that uses GreenSock tools) which makes it extremely accessible and business-friendly while providing a small funding mechanism to sustain ongoing support, enhancement, and innovation. The web is littered with abandoned “open source” projects, but GreenSock has a years-long track record of commitment to the platform. This unique licensing model is a key component of that sustainability. If multiple customers are charged a usage/access/license fee of any kind, please simply sign up for a corporate Club GreenSock membership which comes with a special commercial license granting you permission to do so. Click here for details. Joining the club also gets you members-only bonus plugins, classes, update notifications, and more. Please see the licensing page for details.

Stay up to date

We’d highly recommend checking back frequently and getting updated JavaScript files because we’re actively adding features, patching bugs, implementing workarounds for new browser inconsistencies, etc. Sign up for a free GreenSock account so that you’re on our mailing list and get important notifications. Don’t forget to follow us on Twitter as @greensock and Facebook.

Need help?

There are dedicated forums for all GreenSock tools at http://forums.greensock.com/. Keep in mind that you’ll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified HTML file (and any dependencies) that clearly demonstrates the problem with as little code as possible.

Comments (63)

Subscribe