DEV Community

Cover image for What’s new in GSAP 3
Brian Neville-O'Neill
Brian Neville-O'Neill

Posted on • Originally published at on

What’s new in GSAP 3

Written by Anjolaoluwa Adebayo-Oyetoro✏️

GreenSock has been around for more than a decade, making it one of the oldest JavaScript animation libraries. It works anywhere JavaScript runs and animates both DOM elements and JavaScript objects while maintaining its performance.

GreenSock is backward-compatible, framework-agnostic and easy for developers across all skill levels to pick up. As such, it is one of the most important tools for building intuitive and interactive websites.

The latest version, GSAP 3, comes with about 50 new features and lots of improvements on the previous versions, including:

  • A much easier-to-use API
  • Reduced file size
  • Timeline defaults
  • Brand new utility methods
  • A motion path plugin
  • Backward compatibility
  • Relative position prefixes
  • Advanced staggers
  • Random capabilities

Let’s take a more detailed look at some of the most important new features available in GSAP 3.

LogRocket Free Trial Banner

Simplified API

The new version comes with a simplified, more user-friendly API. GreenSock consolidated the “Lite” and “Max” features, which formed the core modules in the previous versions, into a single object named gsap.

Take the following code, for example, which would have looked like this in previous versions of GSAP.

TweenMax.method('selector', {});
Enter fullscreen mode Exit fullscreen mode

In GSAP 3, the above code would now look like this:

gsap.method('selector', {});
Enter fullscreen mode Exit fullscreen mode

Similarly, the following line would have applied to previous versions.

Enter fullscreen mode Exit fullscreen mode

In GSAP 3, it would translate to the following.

Enter fullscreen mode Exit fullscreen mode

This change also affects the way timelines are created. The two blocks of code below would appear as follows in older versions of GSAP.

const tl = new TimelineMax();

const tl = new TimelineLite();
Enter fullscreen mode Exit fullscreen mode

In the most recent release, it would be written like this:

var tl = gsap.timeline();
tl.method("selector", {});
Enter fullscreen mode Exit fullscreen mode

The gsap object, when chained to a method like to() or from(), returns an instance of a tween.

Reduced file size

GSAP retained almost all of its old functionality and added a host of new features. In addition, GreenSock rebuilt the core from the ground up as modern ES modules.

Backward compatibility

The new GSAP update still recognizes the old syntax, since the Max and Lite features of the previous version are all aliased to keep legacy codebases from breaking. This saves developers the hassle of rewriting codebases to use GSAP 3.


The duration parameter of a tween is now defined in the vars object, as opposed to previous versions where it was defined as a parameter for methods.

Take the following code, written for a previous version of GSAP.

TweenMax.from('selector', 1, {});
Enter fullscreen mode Exit fullscreen mode

In GSAP 3, the above code can be rewritten as:

gsap.from('selctor', {duration:1})
Enter fullscreen mode Exit fullscreen mode

Note: The old syntax still works because the new update is backward-compatible. This helps prevent breaking codebases that use the old syntax.

Timeline defaults

GSAP 3 enables you to specify default properties for your timeline. Child tweens inherit these values on creation.

In the older version, properties were set individually per tween, which led to code repetition. The update helps developers follow the don’t repeat yourself (DRY) principle, keeping code simple and more concise.

The following example is written for older versions of GSAP.

var tl = new TimelineMax();".selector1", 5 , {ease: Power2.Out, x:200})
    .to(".selector2", 5 , {ease: Power2.Out, y:500})
Enter fullscreen mode Exit fullscreen mode

This translates to the following in GSAP 3.

gsap.timeline({defaults:{ease:"power2.out", duration:5}})
    .to(".selector1", {x:200})
    .to(".selector2", {y:500}) 
Enter fullscreen mode Exit fullscreen mode

Each tween inherits the ease and duration from the parent timeline. Inherited defaults are easily overwritten when another value is defined on a child tween.

Advanced staggers

The new update removed methods used to stagger, such as staggerTo(), staggerFrom(), staggerFromTo(). This is now a parameter in the vars object.

You can add staggers to tweens in the following format.

gsap.method("selector", {
  stagger: 1 // adds a stagger of 1 second
Enter fullscreen mode Exit fullscreen mode

You can also perform more advanced staggers by using the object syntax.

gsap.method("selector", {
  stagger: {
    amount:2, // amount of time between staggered tweens
Enter fullscreen mode Exit fullscreen mode

The stagger object also takes in other parameters such as:

  • from, which defines the point where the stagger should begin
  • axis, which defines the axis to be staggered from
  • ease, which defines the type of ease the staggered item should have

New random capabilities

You can now define random value ranges to (such as random(-100, 100)) or an array to be selected from, and GSAP will choose a random value to animate with.

This makes it easier to create advanced randomized effects.

gsap.method("selector", {
  x:"random(100, 200)" //chooses a random number between 1 and 100
Enter fullscreen mode Exit fullscreen mode

Below is an example of using an array.

gsap.method("selector", {
  x:"random([0, 100, 400, 500])" //chooses a number in the array at random
Enter fullscreen mode Exit fullscreen mode

You can even have the random number rounded to the closest increment of any number.

gsap.method("selector", {
  x:"random(-100, 100, 5)" //chooses a random number between -100 and 100 for each target, rounding to the closest 5!
Enter fullscreen mode Exit fullscreen mode

Relative “>” and “<” position prefix

This feature helps with positioning animations in a timeline. It puts a tween relative to the previous tween’s start or end time and removes the need to add labels through your code.

gsap.method('selector',{}, "<" ) //Inserts a tween at the start of the previous tween

gsap.method('selector',{}, ">" ) //Inserts a tween at the end of the previous tween
Enter fullscreen mode Exit fullscreen mode

New utility methods

GSAP has made 15 new utility methods available. Many of them return functions so that they can be added directly to tweens.

These methods include:


Keyframes are a way to define multiple states to which a single tween should be animated instead of creating multiple tweens with the same target.

You can pass an array of keyframes in the vars objects and they’ll be perfectly sequenced.

gsap.method("selector", {keyframes: [
  {x:500, duration:1,delay:2},//adds a delay of 2 seconds before the next animation
  {y:200, duration:1 }
Enter fullscreen mode Exit fullscreen mode

Using GSAP3 in your project

You can use the newest version of GreenSock in your project with either of the following methods.

Using CDN

You can include GSAP 3 in your project using CDN by adding the following to your HTML file.

<script src=""></script>
Enter fullscreen mode Exit fullscreen mode

Installing via package managers

To install via package managers, use the following code.

#Using Yarn

yarn add gsap

#or Using NPM

npm install gsap
Enter fullscreen mode Exit fullscreen mode

Then, import it in your JavaScript file.

import { gsap } from "gsap";
Enter fullscreen mode Exit fullscreen mode


The newly released GSAP 3 includes myriad updates to help you create even more stunning animations. There are more amazing features not covered in this article; for a full list of the updates, read the GSAP 3 release notes. The GreenSock team also put together a list of the top five features to check out in the new release.

Which new features stand out to you? Let us know in the comments section.

Editor's note: Seeing something wrong with this post? You can find the correct version here.

Plug: LogRocket, a DVR for web apps

LogRocket Dashboard Free Trial Banner
LogRocket is a frontend logging tool that lets you replay problems as if they happened in your own browser. Instead of guessing why errors happen, or asking users for screenshots and log dumps, LogRocket lets you replay the session to quickly understand what went wrong. It works perfectly with any app, regardless of framework, and has plugins to log additional context from Redux, Vuex, and @ngrx/store.
In addition to logging Redux actions and state, LogRocket records console logs, JavaScript errors, stacktraces, network requests/responses with headers + bodies, browser metadata, and custom logs. It also instruments the DOM to record the HTML and CSS on the page, recreating pixel-perfect videos of even the most complex single-page apps.
Try it for free.

The post What’s new in GSAP 3 appeared first on LogRocket Blog.

Top comments (0)