Hang in there through the learning curve and you'll discover how addictive it is to animate with code. We promise it's worth your time.

This article covers the most frequently used features but it is not exhaustive. GSAP is a very robust toolset. We'd recommend keeping the GSAP docs handy.

First, let's talk about what GSAP actually does...

GSAP as a property manipulator

Animation ultimately boils down to changing property values many times per second. That's what makes something appear to move, fade, spin, etc. GSAP snags a starting value, an ending value and then interpolates between them, updating roughly 60 times per second.

For example, changing the x coordinate of an object from 0 to 1000 over the course of 1 second makes it move quickly to the right. Gradually changing opacity from 1 to 0 makes an element fade out. Your job as an animator is to decide which properties to change, how quickly, and the "style" of that interpolation (known as easing - we'll get to that later).

To be technically accurate we could have named GSAP the "GreenSock Property Manipulator" (GSPM) but that doesn't have the same ring ;).

DOM, SVG and <canvas>

GSAP doesn't have a pre-defined list of properties it can handle. It's super flexible, adjusting to almost anything you throw at it. GSAP can animate all of the following:

Any numeric value For example, an object that gets rendered to an HTML5 &lt;canvas&gt;. Animate the camera position in a 3D scene or filter values. GSAP is often used with Three.js and Pixi.js.

Once you learn the basic syntax you'll be able to use GSAP anywhere JavaScript runs. This guide will focus on the most popular use case: animating CSS properties of DOM elements.

Loading GSAP

For convenience and loading efficiency, we've combined all the most frequently used tools for DOM / CSS animation into one file called TweenMax, though GSAP contains dozens of highly specialized tools and plugins.

CDN

The simplest way to load GSAP is from the CDN with a <script> tag. TweenMax (and all publicly available GSAP files) are hosted on Cloudfare's super-fast and reliable cdnjs.com.

Demo: TweenMax.to() Basic Usage

If you would like to edit the code and experiment with your own properties and values, just hit theEdit on CodePenbutton.

Notice that the opacity, scale, rotation and x values are all being animated in the demo above but DOM elements don't actually have those properties! In other words, there's no such thing as element.scale or element.opacity. How'd that work then?

CSSPlugin (loaded as a part of TweenMax) automatically notices that the target is a DOM element, so it intercepts the values and works its magic behind the scenes, applying them appropriately as inline styles (element.style.transform and element.style.opacity). Be sure to watch the "Getting Started" video above to see that in action.

Before getting into all the juicy details of how CSSPlugin works, it's best to understand plugins in general.

Plugins

Think of plugins like special properties that are dynamically added to GSAP in order to inject extra abilities. This keeps the core engine small and efficient, yet allows for unlimited expansion. Each plugin is associated with a specific property name.

Because animating CSS properties is so common, GSAP automatically senses when the target is a DOM element and adds a css:{} wrapper. So internally, for example, {x:100, opacity:0.5, onComplete:myFunc} becomes {css:{x:100, opacity:0.5}, onComplete:myFunc}. That way, CSS-related values get routed to the plugin properly and you don't have to do any extra typing.

2D and 3D transforms

CSSPlugin recognizes a number of short codes for transform-related properties:

GSAP

CSS

x: 100

transform: translateX(100px)

y: 100

transform: translateY(100px)

rotation: 360

transform: rotate(360deg)

rotationX: 360

transform: rotateX(360)

rotationY: 360

transform: rotateY(360deg)

skewX: 45

transform: skewX(45deg)

skewY: 45

transform: skewY(45deg)

scale: 2

transform: scale(2, 2)

scaleX: 2

transform: scaleX(2)

scaleY: 2

transform: scaleY(2)

xPercent: 50

transform: translateX(50%)

yPercent: 50

transform: translateY(50%)

GSAP can animate any "transform" value but we strongly recommend using the shortcuts above because they're faster and more accurate (GSAP can skip parsing computed matrix values which are inherently ambiguous for rotational values beyond 180 degrees). The other major convenience GSAP affords is independent control of each component while delivering a consistent order-of-operation.

Performance note: it's much easier for browsers to update x and y (transforms) rather than top and left which affect document flow. So to move something, we recommend animating x and y.

Demo: Multiple 2D and 3D transforms

Additional CSSPlugin notes

Be sure to camelCase all hyphenated properties. font-size should be fontSize, background-color should be backgroundColor.

When animating positional properties such as left and top, its imperative that the elements you are trying to move also have a css position value of absolute, relative or fixed.

vw/vh units aren't currently supported natively, but it's pretty easy to mimic using some JS like x: window.innerWidth * (50 / 100) where 50 is the vw. Just ask in the forums for some help.

from() tweens

Sometimes it's amazingly convenient to set up your elements where they should end up (after an intro animation, for example) and then animate from other values. That's exactly what TweenMax.from() is for.

For example, perhaps your "#logo" element currently has its natural x position at 0 and you create the following tween:

TweenMax.from("#logo", 1, {x:100});

The #logo will immediately jump to an x of 100 and animate to an x of 0 (or whatever it was when the tween started). In other words, it's animating FROM the values you provide to whatever they currently are.

Demo: TweenMax.from() with multiple properties

Special properties (like onComplete)

A special property is like a reserved keyword that GSAP handles differently than a normal (animated) property. Special properties are used to define callbacks, delays, easing and more.

A basic example of a special property is delay:

TweenMax.to("#logo", 1, {x:100, delay:3});

This animation will have a 3-second delay before starting.

Other common special properties are:

onComplete - a callback that should be triggered when the animation finishes.

onUpdate - a callback that should be triggered every time the animation updates/renders

ease - the ease that should be used (like Power2.easeInOut)

Easing

Do you want your animation to feel playful? Robotic? Slick? Realistic? If it had a voice, what would it sound like? To become an animation rock star, you must develop a keen sense of easing because it determines the style of movement between point A and point B. The video below illustrates the basics.

An "ease" controls the rate of change during a tween. The best way to understand the various options is to experiment. Below is an interactive tool that allows you to visually discover how various eases behave. Note: you can click on the underlined parts of the code at the bottom to change things.

For un-precedented control over your eases be sure to check out CustomEase which allows you to literally draw any ease curve you want. CustomWiggle and CustomBounce are advanced eases that create extremely complex and realistic effects.

Callbacks

Callbacks invoke a function when a specific animation event occurs:

onComplete: called when the animation has completed.

onStart: called when the animation begins

onUpdate: called every time the animation updates (on every frame while the animation is active).

onRepeat: called each time the animation repeats (only available in TweenMax and TimelineMax).

onReverseComplete: Function - called when the animation has reached its beginning again from the reverse direction.

To fire a tweenComplete function when an animation finishes, you'd do:

Demo: Basic control methods

Sequencing with Timelines

A timeline is a container for tweens where you place them in time (like a schedule). They can overlap or have gaps between them; you have total control. As the timeline's playhead moves, it scrubs across its child tweens and renders them accordingly! Insert as many as you want and control the entire group as a whole with the standard methods (play(), reverse(), pause(), etc.). You can even nest timelines within timelines!

When to use a timeline

To control a group of animations as a whole

To build a sequence without messing with lots of "delay" values (progressively build so that timing adjustments to earlier animations automatically affect later ones, greatly simplifying experimentation and maintenance)

Control placement with the position-parameter

The secret to building gorgeous, precisely-timed sequences is understanding the position parameter. This one super-flexible parameter controls the placement of your tweens, labels, callbacks, pauses, and even nested timelines.

Timeline control

Timelines and tweens share a common set of control methods. And since any animation's playhead is controlled by its parent timeline, that means pausing a timeline's playhead automatically affects all of its children! Jump to a different time() or progress() on a timeline and all the children will render accordingly.

Getter / Setter methods

Tweens and timelines not only share similar callbacks and control methods, but they also have common methods for getting and setting specific properties of the animation. The most commonly used getter / setter methods are

time(): the local position of the playhead (the current time, in seconds) not including any repeats or repeatDelays.

progress(): the tween's progress which is a value between 0 and 1 indicating the position of the playhead where 0 is at the beginning, 0.5 is halfway complete, and 1 is at the end.

duration(): the animation's duration (in seconds), not including any repeats or repeatDelays.

delay(): the animation's initial delay (the length of time in seconds before the animation should begin).

These methods can be used as setters (by passing in a value) or getters (by omitting all arguments). In the code samples below notice that the duration() method can be used in exactly the same way for both the tween and timeline.

“ @greensock it’s a great library that many people love, and I know you care deeply about performance :) ”

Paul Lewis, ‏@aerotwist

“ I’ve long felt like GSAP is the best kept secret in JavaScript. ”

John Polacek

“ If every library were as robust and reliable as GreenSock’s, the world would be a much better place for software engineers and their clients. I can't think of a better designed or better performing tool, and as a bonus, it's fun as heck to play with. ”

Thomas Summerall

“ There is no doubt that GreenSock is currently the best available tool for creating astonishing interactive websites and animation effects. ”

Petr Tichy

“ The GreenSock animation platform is one of the most useful sets of tools in existence when it comes to web animation. ”

Ben Rugg

“ GreenSock is the best thing that happened to SVG animations since SVG animations. ”

Sara Soueidan

“ This stuff is so incredibly amazing I can't believe it. The level of details and options put into these things and the natural instinct GreenSock has for solving everyday problems is impressive. ”

Jens Ahrengot Boddum

“ GSAP was a revelation for me to be compared with the introduction of jQuery ”

Jan Paepke, @janpaepke

“ After searching around the web for alternatives, I found GreenSock to be the most performant. ”

Lamin Sanneh

Thanks for signing up!

Now you'll begin receiving the latest GreenSock updates, exclusive offers, and more right in your inbox. Welcome aboard.