The New Features of GSAP 3

In this article we will explore many of the new features available from GSAP 3. The GreenSock animation library is a JavaScript library many front-end developers turn to because it can be easy to get started and you can create powerful animations with a lot of control. Now with GSAP 3 getting started with GreenSock is even easier.

Some of the new features we will cover in this article are:

• GreenSock’s smaller file size
• A Simplified API which offers a newer syntax
• Defaults in timelines
• Easier to use with build tools and bundlers
• Advanced stagger everywhere!
• Keyframes
• MotionPath and MotionPath plugin
• use of Relative “>” and “<” position prefix in place of labels in Timelines
• The new “effects” extensibility
• Utility methods

…and more!

GreenSock’s smaller file size

First and foremost the GreenSock library is now even smaller. It still packs all the amazing features I love, plus more (50+ more to be exact). But it is now about half the size! We will see some of the reasons below like the new simplified API but at its core GSAP was completely rebuilt as modern ES modules.

A Simplified API

With the new version of GreenSock we no longer have to decide whether we want to use TweenMax, TweenLite, TimelineMax, or TimelineLite. Now, everything is in a single simplified API so instead of code that looks like this:

TweenMax.to('.box', 1, {
  scale: 0.5,
  y: 20,
  ease: Elastic.easeOut.config( 1, 0.3)
})

We can write this instead:

gsap.to(".box1",{
  duration: 1,
  scale: 0.5,
  y: 20     // or you can now write translateY: 20,
  ease: "elastic(1, 0.3)",
});

Creating Timelines is easier too. Instead of using new TimelineMax() or new TimelineLite() to create a timeline, you now just use gsap.timeline() (simpler for chaining).

Here is an example of the first syntax change. Note that the old syntax still works in GSAP 3 for backward compatibility. According to GreenSock, most legacy code still works great.

See the Pen GreenSock New vs Old syntax by Christina Gorton (@cgorton) on CodePen.

Duration

Previously, the animation’s duration was defined as its own parameter directly after the target element. Like this:

TweenMax.to('.box', 1, {})

With the new version, duration is defined in the same vars object as the rest of the properties you animate and therefore is more explicit.

gsap.to(".box",{
  duration: 2,
});

This adds several benefits such as improved readability. After working with and teaching GSAP for a while now, I agree that having an explicit duration property is helpful for anyone new to GreenSock and those of us who are more experienced. This isn’t the only thing the new API improves though. The other benefits will become more obvious when we look at defaults in timelines and the new Keyframes.

Defaults in timelines

This new feature of GSAP is really wonderful for anyone who creates longer animations with gsap.timeline(). In the past when I would create long animations I would have to add the same properties like ease, duration, and more to each element I was animating in a timeline. Now with defaults I can define default properties that will be used for all elements that are animated unless I specify otherwise. This can greatly decrease the amount of code you are writing for each timeline animation.

Let’s take a look at an example:

This Pen shows a couple of the new features in GSAP 3 but for now we will focus on the defaults property.

See the Pen Quidditch motionPath by Christina Gorton (@cgorton) on CodePen.

I use defaults in a few places in this pen but one timeline in particular shows off its power. At the beginning of this timeline I set defaults for the duration, ease, yoyo, repeat, and the autoAlpha property. Now instead of writing the same properties for each tween I can write it one time.

const moving = () => {
  let tl = new gsap.timeline({ 
    defaults: { 
      duration: .02,  
      ease: "back(1.4)", 
      yoyo: true, 
      repeat: 1, 
      autoAlpha: 1 
    }
  })
  tl.to('.wing1',{})
    .to('.wing2',{})
    .to('.wing3',{})
  
  return tl;
}




Without the defaults my code for this timeline would look like this:

const moving = () => {
  let tl = gsap.timeline()
  
  tl.to('.wing1',{
    duration: .02,  
    ease: "back(1.4)", 
    yoyo: true, 
    repeat: 1, 
    autoAlpha: 1
  })
  .to('.wing2',{
    duration: .02,  
    ease: "back(1.4)", 
    yoyo: true, 
    repeat: 1, 
    autoAlpha: 1
  })
  .to('.wing3',{
    duration: .02,  
    ease: "back(1.4)", 
    yoyo: true, 
    repeat: 1, 
    autoAlpha: 1
  })

  return tl;
}

That is around a 10 line difference in code!

Use of Relative > and < position prefix in place of labels in Timelines

This is another cool feature to help with your timeline animations. Typically when creating a timeline I create labels that I then use to add delays or set the position of my Tweens.

As an example I would use tl.add() to add a label then add it to my tween along with the amount of delay I want to use relative to that label.

The way I previously used labels would look something like this:

gsap.timeline()
  .add("s")
  .to(“.box1", { ... }, "s")
  .to(“.box2", { ... }, "s")
  .to(“.box3", { ... }, "s+=0.8")
  .to(“.box4", { ... }, "s+=0.8”);

See an example here.

With > and < you no longer need to add a label.

From the GreenSock docs:

“Think of them like pointers – “<” points to the start, “>” points to the end (of the most recently-added animation).”

• “<” references the most recently-added animation’s START time
• “>” references the most recently-added animation’s END time

So now a timeline could look more like this:

gsap.timeline()
  .to(“.box1", { ... })
  .to(“.box2", { ... }, "<")
  .to(“.box3", { ... }, "<0.8")
  .to(“.box4", { ... }, "<”);

And you can offset things with numbers like I do in this example:

See the Pen MotionPath GreenSock v3 by Christina Gorton (@cgorton) on CodePen.

Stagger all the things

Previously in GSAP to stagger animations you had to define it at the beginning of a tween with either a staggerTo(), staggerFrom(), or staggerFromTo() method. In GSAP 3 this is no longer the case. You can simply define your stagger in the vars object like this:

tl.to(".needle",{
  scale: 1,
  delay:0.5,
  stagger: 0.5 //simple stagger of 0.5 seconds
},"start+=1")




…or for a more advanced stagger you can add extra properties like this:

tl.to(".needle",{
  scale: 1,
  delay:0.5,
  stagger: {
    amount: 0.5, //  the total amount of time (in seconds) that gets split up among all the staggers. 
    from: "center" // the position in the array from which the stagger will emanate
  }
},"start+=1")




This animation uses staggers in several places. like the needles. Check out all the staggers in this pen:

See the Pen Cute Cactus stagger by Christina Gorton (@cgorton) on CodePen.

Easier to use with build tools and bundlers

When I have worked on Vue or React projects in the past working with GreenSock could be a little bit tricky depending on the features I wanted to use.

For example in this Codesandbox I had to import in TweenMax, TimelineMax and any ease that I wanted to use.

import { TweenMax, TimelineMax, Elastic, Back} from "gsap";

Now with GSAP 3 my import looks like this:

import gsap from "gsap";

You no longer have to add named imports for each feature since they are now in one simplified API. You may still need to import extra plugins for special animation features like morphing, scrollTo, motion paths, etc.

Keyframes

If you have ever worked with CSS animations then keyframes will be familiar to you.

So what are keyframes for in GreenSock?

In the past if you wanted to animate the same set of targets to different states sequentially (like “move over, then up, then spin”), you would need to create a new tween for each part of the sequence. The new keyframes feature lets us do that in one Tween!

With This property you can pass an array of keyframes in the same vars objects where you typically define properties to animate and the animations will be nicely sequenced. You can also add delays that will either add gaps (positive delay) or overlaps (negative delay).

Check out this example to see the keyframes syntax and the use of delays to overlap and add gaps in the animation.

See the Pen GreenSock Keyframes by Christina Gorton (@cgorton) on CodePen.

MotionPath and MotionPath helper plugin

One of the features I am most excited about is MotionPathPlugin and the MotionPathHelper. In the past I used MorphSVGPlugin.pathDataToBezier to animate objects along a path. Here is an example of that plugin:

See the Pen MorphSVGPlugin.pathDataToBezier with StaggerTo and Timeline by Christina Gorton (@cgorton) on CodePen.

But the MotionPathPlugin makes it even easier to animate objects along a path. You can create a path for your elements in two ways:

• With an SVG path you create
• Or with manual points you define in your JavaScript

The previous Quidditch pen I shared uses MotionPathPlugin in several places. First you need to register it like this:

//register the plugin
gsap.registerPlugin(MotionPathPlugin);

Note: the MotionPathHelper plugin is a premium feature of GreenSock and is available to Club GreenSock members but you can try it out for free on CodePen.

I used an SVG editor to create the paths in the Quidditch animation and then I was able to tweak them directly in the browser with the MotionPathHelper! The code needed to add the MotionPathHelper is this

MotionPathHelper.create(element)

I then clicked “COPY MOTION PATH” and saved the results in variables that get passed to my animation(s).

Paths created with the MotionPathPlugin helper

const path = "M-493.14983,-113.51116 C-380.07417,-87.16916 -266.9985,-60.82716 -153.92283,-34.48516 -12.11783,-77.91982 129.68717,-121.35449 271.49217,-164.78916 203.45853,-70.96417 186.21594,-72.24109 90.84294,-69.64709   ",
      path2 ="M86.19294,-70.86509 C64.53494,-36.48609 45.53694,-13.87709 -8.66106,-8.17509 -23.66506,-40.23009 -30.84506,-44.94009 -30.21406,-88.73909 6.79594,-123.26109 54.23713,-91.33418 89.94877,-68.52617 83.65113,-3.48218 111.21194,-17.94209 114.05694,18.45191 164.08394,33.81091 172.43213,34.87082 217.26913,22.87582 220.68213,-118.72918 95.09713,-364.56718 98.52813,-506.18118  ",
      path3 = "M-82.69499,-40.08529 C-7.94199,18.80104 66.81101,77.68738 141.56401,136.57371 238.08201,95.81004 334.60001,55.04638 431.11801,14.28271 ",
      path4 = "M126.51311,118.06986 C29.76678,41.59186 -66.97956,-34.88614 -163.72589,-111.36414 -250.07922,-59.10714 -336.43256,-6.85014 -422.78589,45.40686 ";

Example of a path passed in to animation

const hover = (rider, path) => {
  let tl = new gsap.timeline();
  tl.to(rider, {
    duration: 1,
    ease: "rider",
    motionPath:{
      path: path,
    }
  })
  return tl
}

In this timeline I set up arguments for the rider and the path so I could make it reusable. I add which rider and which path I want the rider to follow in my master timeline.

.add(hover("#cho", path3),'start+=0.1')
.add(hover("#harry", path4),'start+=0.1')

If you want to see the paths and play around with the helper plugin you can uncomment the code at the bottom of the JavaScript file in this pen:

See the Pen Quidditch motionPath by Christina Gorton (@cgorton) on CodePen.

Or, in this pen you can check out the path the wand is animating on:

See the Pen MotionPath GreenSock v3 by Christina Gorton (@cgorton) on CodePen.

Effects

According the the GreenSock Docs:

Effects make it easy for anyone to author custom animation code wrapped in a function (which accepts targets and a config object) and then associate it with a specific name so that it can be called anytime with new targets and configurations

So if you create and register an effect you reuse it throughout your codebase.

In this example I created a simple effect that makes the target “grow”. I create the effect once and can now apply it to any element I want to animate. In this case I apply it to all the elements with the class “.box”

See the Pen GreenSock Effects by Christina Gorton (@cgorton) on CodePen.

Utility methods

Lastly, I’ll cover the utility methods which I have yet to explore extensively but they are touted as a way to help save you time and accomplish various tasks that are common with animation.

For example, you can feed any two similarly-typed values (numbers, colors, complex strings, arrays, even multi-property objects) into the gsap.utils.interpolate() method along with a progress value between 0 and 1 (where 0.5 is halfway) and it’ll return the interpolated value accordingly. Or select a random() value within an array or within a specific range, optionally snapping to whatever increment you want.

Most of the 15 utility methods that can be used separately, combined, or plugged directly into animations. Check out the docs for details.

Below I set up one simple example using the distribute() utility which:

Distributes an amount across the elements in an array according to various configuration options. Internally, it’s what advanced staggers use, but you can apply it for any value. It essentially assigns values based on the element’s position in the array (or in a grid)

See the Pen GreenSock Utility Methods by Christina Gorton (@cgorton) on CodePen.

For an even more impressive example check out Craig Roblewsky’s pen that uses the distribute() and wrap() utility methods along with several other GSAP 3 features like MotionPathPlugin:

See the Pen MotionPath Distribute GSAP 3.0 by Craig Roblewsky (@PointC) on CodePen.

That wraps up the features we wanted to cover in this article. For the full list of changes and features check out this page and the GreenSock docs. If you’d like to know what old v2 code isn’t compatible with v3, see GreenSock’s list. But there’s not much as GSAP 3 is surprisingly backward-compatible given all the improvements and changes.

References

All of the Pens from this article can be found in this collection.

For more examples check out GreenSock’s Showcase and Featured GSAP 3 Pens collection.