TimelineMax: A Primer

What is TimelineMax? What makes it different from other GreenSock Animation Platform (GSAP) libraries? Why would I need TimelineMax over TimelineLite? How do I go about understanding parameters for TimelineMax? If you find yourself asking any of these questions then you’ve come to the right place.

Welcome to the primer for a Tuts+ series discussing TimelineMax by GreenSock. Get ready for an explosive, mind bending series to help mold you into an animation pro.

What is TimelineMax?

TimelineMax is a JavaScript sequencing tool which acts as a container for tweens and other timelines, making it easier to control them as a whole and precisely manage their timing. TimelineMax provides methods to allow access to multiple aspects of your animation. It can also dynamically adjust a timeline’s speed at runtime, plus much, much more.

Note: tweening is an abbreviation of inbetweening; creating frames between states in an animation sequence.

TimelineMax extends TimelineLite, offering exactly the same functionality along with additional (but non-essential) features like:

repeat
repeatDelay
yoyo
currentLabel()
tweenTo()
tweenFromTo()
getLabelAfter()
getLabelBefore()
and getActive()

Benefits and Features

TimelineMax allows you, as an author, the power to make tweens overlap on the timeline as much as you desire. As the animation pro, you have complete control over where tweens are placed on the timeline. Most other animation tools can primarily execute a basic one-after-the-other sequencing, but can’t allow tweens to overlap. Imagine appending a tween that moves an object and you’d like it to start fading out 0.5 seconds before the end of that tween? With TimelineMax it’s a great deal cleaner, plus extremely robust to make all that happen.

For convenience, major plugins like CSSPlugin (for supplying CSS vendor prefixes), RoundPropsPlugin, DirectionalRotationPlugin, AttrPlugin and BezierPlugin are all included with TweenMax and TimelineMax. Since TweenMax will provide you with TimelineMax and all the other goodies previously listed, GreenSock recommends using TweenMax for most use cases. Loading TweenMax is just more convenient as one file contains pretty much all you need.

Installing

To start, you’ll need to get the TweenMax script and load it into your HTML document prior to your custom animation script. Lucky for us CDNJS has a copy available for us (there’s also one on GitHub).

<html>
  <body>
<script src="//cdnjs.cloudflare.com/ajax/libs/gsap/1.14.2/TweenMax.min.js"></script>
    <script src="my-timelinemax-animation.js"></script>
  </body>
</html>

Config

TimelineMax allows for custom configuration options through the use of an object literal. Let’s explore what that looks like.

TimelineMax(vars: {})

The part you see using the {} curly braces is the object literal which will hold our configuration. This means we can insert key:value pairings within those braces to define how our timeline will behave. The entire line TimelineMax(vars: {}) is what’s referred to in the TimelineMax docs as the “Constructor.”

Here’s the entire TimelineMax config with each key given its default value. Place this right at the top of your JavaScript animation file (which we called “my-timelinemax-animation.js” in our example above). We're only listing the entire config here so you can see the variety of configuration options TimelineMax offers. Typically your configuration object will only contain the properties needed for adjustments. You can read more about these options in the TimelineMax documentation.

var tmax_options = {
  delay: 0,
  paused: false,
  onComplete: function() {
    console.log('animation is complete');
  },
  onCompleteScope: {},
  tweens: [],
  stagger: 0,
  align: 'normal',
  useFrames: false,
  onStart: function() {
    console.log('on start called');
  },
  onStartScope: {},
  onUpdate: function() {
    console.log('on update called');
  },
  onUpdateScope: {},
  onRepeat: function() {
    console.log('on repeat called');
  },
  onRepeatScope: {},
  onReverseComplete: function() {
    console.log('on reverse complete');
  },
  onReverseCompleteScope: {},
  autoRemoveChildren: false,
  smoothChildTiming: false,
  repeat: 0,
  repeatDelay: 0,
  yoyo: false,
  onCompleteParams: [],
  onReverseCompleteParams: [],
  onStartParams: [],
  onUpdateParams: [],
  onRepeatParams: []
};

Now that you have the config in place and understand it's options, you can pass your custom object literal config to the TimelineMax() constructor, so add the following to the bottom of your file:

var tmax_tl = new TimelineMax(tmax_options);

Your First Animation

Tweens are created using methods like to(), from() and staggerFrom() just to name a few. As you saw previously we took our options object and passed it as an argument to the TimelineMax constructor. Now we’ll need to move a few objects to get our feet wet. For the sake of simplicity let’s move two circles from the left and the top of the viewport:

Check the JS tab in the example above to see how the effect is achieved. As noted previously, I’ve setup the TimelineMax constructor for the scene above and passed in the object literal containing the timeline’s options:

var tl        = new TimelineMax(tmax_options)

Each circle contains an id for me to reference them by:

var tl        = new TimelineMax(tmax_options),
    circle_top    = $('#circle-top'),
    circle_bottom = $('#circle-bottom');

and then the to() method is used in order to control the tween.

tl.to(circle_top, 1, { left: 100 })
  .to(circle_bottom, 1, { top: 100 });

Within to() we’re effectively saying “use the element that’s passed as the first argument and move it from the left 100px. Then use the to() method chained after our first to() method to do the same, but move that element from the top 100px.”

Take note that the circle moving from the top is triggered once the circle moving from the left has completed its movement (tween). We’ll learn in upcoming tutorials how to control elements at different times and speed along the timeline using the position parameter.

Next Time

If you’d like to jump ahead on this animation journey feel free to head on over to the GreenSock getting started documentation. Stay tuned in for the next in the series of this animation adventure where I cover things such as labels, offsets, pauses, arguments and learning how to tweak options to eleven. Until next time!