New Tween/Timeline Syntax (optional)​

The old syntax still works, but technically you never need to reference TweenMax, TweenLite, TimelineMax or TimelineLite anymore because they're all simplified into a singlegsap object!

// old
TweenMax.to(".class",2,{x:100});

// new
gsap.to(".class",{duration:2,x:100});

// -- Timelines --

// old
var tl=newTimelineMax();

// new
var tl= gsap.timeline();

Notice there's no "new" keyword needed to create thetimeline.

Internally, there's one "Tween" class (replaces TweenLite/TweenMax) and one "Timeline" class (replaces TimelineLite/TimelineMax), and both haveall of the features like repeat, yoyo, etc. When you call one of thegsap methods like.to(),.from(), etc., it returns an instance of the appropriate class with easily chainable methods. You never need to wonder which flavor (Lite/Max) you need.

So for the vast majority of your code, you could simply replace TweenLite and TweenMax with "gsap". You could also do a search/replace for "new TimelineLite(" and "new TimelineMax(", replacing them with "gsap.timeline(" (notice we left off the closing ")" so that any vars objects are retained, like if you had "new TimelineMax({repeat:-1})" it'd keep the repeat).

Duration (optional)​

You can still define a tween's duration as the 2nd parameter, but in GSAP 3 we encourage you to define it inside the vars object instead because it's more readable, it fits with the new keyframes feature, and can be function-based:

// old
TweenMax.to(obj,1.5,{...});
TweenMax.from(obj,1.5,{...});
TweenMax.fromTo(obj,1.5,{...},{...});

// new
gsap.to(obj,{duration:1.5,...});
gsap.from(obj,{duration:1.5,...});
gsap.fromTo(obj,{...},{duration:1.5,...});

Easing (optional)​

The old eases still work great, but you can switch to the new, more compact ease format that requires less typing, is more readable, and eliminates import hassles. Simply include the ease name (all lowercase) followed by a dot and then the type (".in",".out", or".inOut"). Note that.out is the default so you can omit that completely.

// old
ease:Power3.easeInOut
ease:Sine.easeOut
ease:Linear.easeNone
ease:Elastic.easeOut.config(1,0.5)
ease:SteppedEase.config(5);

// new
ease:"power3.inOut"
ease:"sine"// the default is .out
ease:"none"// shortened keyword
ease:"elastic(1, 0.5)"
ease:"steps(5)"

Notice that for eases that support additional inputs, simply put them within some parenthesis at the end:

// old
ease:Elastic.easeOut.config(1,0.3)
ease:Elastic.easeIn.config(1,0.3)

// new
ease:"elastic(1, 0.3)"// the default is .out
ease:"elastic.in(1, 0.3)"

RoughEase,SlowMo, andExpoScaleEase are not included in the core GSAP file - they're in an external EasePack file.

We highly recommend using ourEase Visualizer to get the exact ease that you want and easily copy the correct formatting.

Staggers (optional)​

The old stagger methods still exist for legacy code, but GSAP 3 supports staggers in ANY tween! Simply use thestagger property within the vars parameter.

// old
TweenMax.staggerTo(obj,0.5,{...},0.1);

// new
// Simple stagger
gsap.to(obj,{...,stagger:0.1});

// Complex stagger
gsap.to(obj,{...,stagger:{
each:0.1,
from:"center"
grid:"auto"
}});

Overwriting​

Prior to GSAP 3, the defaultoverwrite mode was"auto" which analyzes the tweens of the same target that are currently active/running and only overwrites individual properties that overlap/conflict, but in GSAP 3 the default mode isfalse meaning it won't check for any conflicts or apply any overwriting. Why? The overwrite behavior sometimes confused people, plus it required extra processing. We wanted to streamline things in GSAP 3 and make overwriting behavior an opt-in choice.

To get the GSAP 1.x/2.x behavior, simply do this once:

// set the default overwrite mode to "auto", like it was in GSAP 1.x/2.x
gsap.defaults({overwrite:"auto"});

Of course you can set overwrite on a per-tween basis too (in the vars object).

Also note that there were more overwrite modes in GSAP 1.x/2.x (like "concurrent", "preexisting" and "allOnStart") that have been eliminated in GSAP 3 to streamline things. Now the only options are"auto" (isolates only specific overlapping/conflicting properties),false (no overwriting), ortrue (when the tween starts, it immediately kills all other tweens of the same target regardless of which properties are being animated).

onOverwrite was removed in favor of a newonInterrupt callback that fires if/when the tween is killed before it completes. This could happen because its kill() method is called or due to overwriting.

Plugins​

Loading plugins​

Similar to the oldTweenMax, some plugins are already included in GSAP's core so that they don't need to be loaded separately. These are calledcore plugins and includeAttrPlugin,CSSPlugin,ModifiersPlugin, andSnapPlugin. RoundPropsPlugin is also included for legacy code, but it has been replaced by the more flexible SnapPlugin.

Other plugins, such asDraggable,MotionPathPlugin,MorphSVGPlugin, etc. need to be loaded separately and registered usinggsap.registerPlugin(). We recommend using theGSAP Installation Helper to get sample code showing how to load and register each file.

// register plugins (list as many as you'd like)
gsap.registerPlugin(MotionPathPlugin,TextPlugin,MorphSVGPlugin);

MotionPathPlugin replaces BezierPlugin​

GSAP's newMotionPathPlugin is essentially a better, more flexible version of the older BezierPlugin. In most cases, you can just changebezier legacy references tomotionPath:

// old
bezier:[{x:200,y:100},{x:400,y:0},{x:300,y:200}]

// new
motionPath:[{x:200,y:100},{x:400,y:0},{x:300,y:200}]

Keep in mind that MotionPathPlugin also supports SVG paths! If you're having trouble converting your bezier curve to a motion path, feel free to post inour forums.

The oldtype: "soft" of BezierPlugin isn't available directly in MotionPathPlugin (it was rarely used), but there's a helper function inthis forums post that'll deliver identical results.

className tweens removed​

Support for class name tweens has been removed since they're not very performant, they're less clear, and required an uncomfortable amount of kb. Plus they were rarely used. Just use regular tweens instead that explicitly animate each property.

For example if you had this CSS:

.box{
width: 100px;
height: 100px;
  background-color: green;
}
.box.active{
  background-color: red;
}

You could use this #"0">// old
.to(".class",0.5,{className:"+=active"})

// new
.to(".class",{backgroundColor:"red"})

// if you need to add a class name in the end, you could do this instead:
.to(".class",{backgroundColor:"red",onComplete:function(){
this.targets().forEach(elem=> elem.classList.add("active"));
}})


// old
TweenMax.to(myObject,0.5,{colorProps:{borderColor:"rgb(204,51,0)"}});

// new
gsap.to(myObject,{borderColor:"rgb(204,51,0)",duration:0.5});

// old
CSSPlugin.suffixMap.left="%";

// new
gsap.config({units:{"left":"%"}})

// old
TweenMax.staggerTo(".class",0.5,{cycle:{x:[-100,100]}},0.1)

// new
gsap.to(".class",{x: gsap.utils.wrap([-100,100]),stagger:0.1})

// old
TweenLite.ticker.addEventListener("tick", myFunction);
TweenLite.ticker.removeEventListener("tick", myFunction);

// new
gsap.ticker.add(myFunction);
gsap.ticker.remove(myFunction);

gsap.defaults({
ease:"power2.in",
overwrite:"auto",
smoothOrigin:false,
transformPerspective:500,
duration:1
});

var tl= gsap.timeline({defaults:{
ease:"power2.in",
duration:1
}});

// now tweens created using tl.to(), tl.from(), and tl.fromTo() will use the
// above values as defaults

gsap.config({
autoSleep:60,
force3D:false,
nullTargetWarn:false,
units:{left:"%",top:"%",rotation:"rad"}
});

// old
TweenMax.to(obj,0.5,{...,onCompleteScope: anotherObj,onComplete:function(){
console.log(this);// logs anotherObj
}});

// new
gsap.to(obj,{...,callbackScope: anotherObj,onComplete:function(){
console.log(this);// logs anotherObj
}});

// or
gsap.to(obj,{...,onComplete:function(){
console.log(this);// logs anotherObj
}.bind(anotherObj)});

// old
TweenMax.to(obj,0.5,{onComplete:function(){
console.log(this.target);
}});


// new
gsap.to(obj,{onComplete:function(){
console.log(this.targets());// an array
}});

gsap.to(".class",{
// BE CAREFUL! Arrow functions lock scope to where they were created, so "this" won't refer to the tween instance here!
// Use normal functions if you need "this" to refer to the tween instance.
onComplete:()=>console.log(this.targets())// will not work
});

// this function will always push the tween instance into the parameters for you and allow you to define a scope.
functioncallback(func, scope, params){
let tween;
  params= params||[];
returnfunction(){
if(!tween){
      tween=this;
      params.push(tween);
}
    func.apply(scope|| tween, params);
};
}

gsap.to(...{
onComplete:callback(tween=>{
console.log(this);// since this is an arrow function, scope is locked anyway so this is your class instance
console.log(tween);// tween instance
})
});

// old
element._gsTransform.x

// new
gsap.getProperty(element,"x")