Jump to content
GreenSock

Search In
  • More options...
Find results that contain...
Find results in...

Timeline Tip: Understanding the Position Parameter


| GreenSock
201679

The secret to building gorgeous sequences with precise timing is understanding the position parameter which is used in many methods throughout GSAP. This one super-flexible parameter controls the placement of your tweens, labels, callbacks, pauses, and even nested timelines, so you'll be able to literally place anything anywhere in any sequence.

Watch the video

For a quick overview of the position parameter, check out this video from the "GSAP 3 Express" course by Snorkl.tv - one of the best ways to learn the basics of GSAP 3.

Using position with gsap.to()

This article will focus on the gsap.to() method for adding tweens to a Tween, but it works the same in other methods like from(), fromTo(), add(), etc. Notice that the position parameter comes after the vars parameter:

.to( target, vars, position )

Since it's so common to chain animations one-after-the-other, the default position is "+=0" which just means "at the end", so timeline.to(...).to(...) chains those animations back-to-back. It's fine to omit the position parameter in this case. But what if you want them to overlap, or start at the same time, or have a gap between them? No problem.

Multiple behaviors

The position parameter is super flexible, accommodating any of these options:

  • Absolute time (in seconds) measured from the start of the timeline, as a number like 3

    // insert exactly 3 seconds from the start of the timeline
    tl.to(".class", {x: 100}, 3);
  • Label, like "someLabel". If the label doesn't exist, it'll be added to the end of the timeline.

    // insert at the "someLabel" label
    tl.to(".class", {x: 100}, "someLabel");
  • "<" The start of previous animation**. Think of < as a pointer back to the start of the previous animation.

    // insert at the START of the  previous animation
    tl.to(".class", {x: 100}, "<");
  • ">" - The end of the previous animation**. Think of > as a pointer to the end of the previous animation.

    // insert at the END of the previous animation
    tl.to(".class", {x: 100}, ">");
  • A complex string where "+=" and "-=" prefixes indicate relative values. When a number follows "<" or ">", it is interpreted as relative so "<2" is the same as "<+=2". Examples:

    • "+=1" - 1 second past the end of the timeline (creates a gap)
    • "-=1" - 1 second before the end of the timeline (overlaps)
    • "myLabel+=2" - 2 seconds past the label "myLabel"
    • "<+=3" - 3 seconds past the start of the previous animation
    • "<3" - same as "<+=3" (see above) ("+=" is implied when following "<" or ">")
    • ">-0.5" - 0.5 seconds before the end of the previous animation. It's like saying "the end of the previous animation plus -0.5"
  • A complex string based on a percentage. When immediately following a "+=" or "-=" prefix, the percentage is based on total duration of the animation being inserted. When immediately following "&lt" or ">", it's based on the total duration of the previous animation. Note: total duration includes repeats/yoyos. Examples:

    • "-=25%" - overlap with the end of the timeline by 25% of the inserting animation's total duration
    • "+=50%" - beyond the end of the timeline by 50% of the inserting animation's total duration, creating a gap
    • "<25%" - 25% into the previous animation (from its start). Same as ">-75%" which is negative 75% from the end of the previous animation.
    • "<+=25%" - 25% of the inserting animation's total duration past the start of the previous animation. Different than "<25%" whose percentage is based on the previous animation's total duration whereas anything immediately following "+=" or "-=" is based on the inserting animation's total duration.
    • "myLabel+=30%" - 30% of the inserting animation's total duration past the label "myLabel".

Basic code usage

tl.to(element, 1, {x: 200})
  //1 second after end of timeline (gap)
  .to(element, {duration: 1, y: 200}, "+=1")
  //0.5 seconds before end of timeline (overlap)
  .to(element, {duration: 1, rotation: 360}, "-=0.5")
  //at exactly 6 seconds from the beginning of the timeline
  .to(element, {duration: 1, scale: 4}, 6);

It can also be used to add tweens at labels or relative to labels

//add a label named scene1 at an exact time of 2-seconds into the timeline
tl.add("scene1", 2)
  //add tween at scene1 label
  .to(element, {duration: 4, x: 200}, "scene1")
  //add tween 3 seconds after scene1 label
  .to(element, {duration: 1, opacity: 0}, "scene1+=3");

Sometimes technical explanations and code snippets don't do these things justice. Take a look at the interactive examples below.

No position: Direct Sequence

If no position parameter is provided, all tweens will run in direct succession.

1.0
1
2
3
4
  
//all tweens run in direct succession
var tl = gsap.timeline();
tl.to("#green", {duration: 1, x: 750})
  .to("#blue", {duration: 1, x: 750})
  .to("#orange", {duration: 1, x: 750})
  

Positive Relative: Gaps / Delays

Use a positive, relative value ("+=X") to place your tween X seconds after previous animations end

1.0
1
2
3
4
  
//there is a 1 second gap between tweens
var tl = gsap.timeline();
tl.to("#green", {duration: 1, x: 750})
  // insert 1 second after end of timeline
  .to("#blue", {duration: 1, x: 750}, "+=1")
  // insert 1 second after end of timeline
  .to("#orange", {duration: 1, x: 750}, "+=1")
  

Negative Relative: Overlap

Use a negative, relative value ("-=X") to place your tween X seconds before previous animations end

1.0
1
2
3
4
  
//tweens overlap
var tl = gsap.timeline();
tl.to("#green", {duration: 2, x: 750})
   // insert 1 second before end of timeline
  .to("#blue", {duration: 2, x: 750}, "-=1")
   // insert 1 second before end of timeline
  .to("#orange", {duration: 2, x: 750}, "-=1");
  

Absolute: Anywhere

Use an absolute value (number) to specify the exact time in seconds a tween should start.

1.0
1
2
3
4
  
//tweens are inserted at absolute position
var tl = gsap.timeline();
tl.to("#green", {duration: 4, x: 750})
  //insert tween 1 second into timeline
  .to("#blue", {duration: 2, x: 750}, 1)
  //insert tween 1 second into timeline
  .to("#orange", {duration: 2, x: 750}, 1);
  

Labels

Use a label ("string") to specify where a tween should be placed.

1.0
blueGreenSpin
1
2
3
4
  
//tweens are inserted at and relative to a label's position
var tl = gsap.timeline();
tl.to("#green", {duration: 1, x: 750})
  //add blueGreenSpin label 1 second after end of timeline
  .add("blueGreenSpin", "+=1")
  //add tween at blueGreenSpin label
  .to("#blue", {duration: 2, x: 750, rotation: 360}, "blueGreenSpin")
  //insert tween 0.5 seconds after blueGreenSpin label
  .to("#orange", {duration: 2, x: 750, rotation: 360}, "blueGreenSpin+=0.5");
  

Relative to other tweens

Use "<" to reference the most recently-added animation's START time. Use ">" to reference the most recently-added animation's END time.

1.0
1
2
3
4
  
//tweens are inserted at absolute position
var tl = gsap.timeline();
tl.to("#green", {duration: 1, x: 750})
  //insert tween at the end of the previous tween
  .to("#blue", {duration: 2, x: 750}, ">")
  //insert tween at the start of the previous tween
  .to("#orange", {duration: 2, x: 750}, "<");
  

Percentage-based values

As of GSAP 3.7.0, you can use percentage-based values, as explained in this video:

Interactive Demo

See the Pen Position Parameter Interactive Demo by GreenSock (@GreenSock) on CodePen.

Hopefully by now you can see the true power and flexibility of the position parameter. And again, even though these examples focused mostly on timeline.to(), it works exactly the same way in timeline.from(), timeline.fromTo(), timeline.add(), timeline.call(), and timeline.addPause().

*Percentage-based values were added in GSAP 3.7.0
**The "previous animation" refers to the most recently-inserted animation, not necessarily the animation that is closest to the end of the timeline.

  • Like 2
  • Thanks 1

Get an all-access pass to premium plugins, offers, and more!

Join the Club

When is the last time you worked on something you love? Go animate something cool and then share it with us.

- Team GreenSock



User Feedback

Recommended Comments

One thing I am having trouble understanding is the position paramater and duration in context to when the timeline is attached to the scroll. It doesn't behave like a normal tween does and things get really weird. I haven't seen any demo's here on that, I was wondering if someone might have something that explains it a little more?

For example...on my scroll trigger timeline I have a duration of 2 on each element, but when I scroll through the timeline you can barely see them as they zip by. Is there a conversion from seconds to scroll or something like that?

Link to comment
Share on other sites

There is a small error in the example for the "Relative to other tweens" section. The first tween's duration is 1, not 4.

Link to comment
Share on other sites



Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

×