When should I use labels vs numeric positions?

Use labels when the same beat is referenced by multiple tweens or by separate timelines. They make the choreography self-documenting and survive duration changes - if you slow down an earlier tween, the labeled beat shifts but anything anchored to the label follows. Use numeric positions for one-off overlap/gap fine-tuning.

What's the difference between '<' and '<=0'?

They behave the same for the parallel case. `'<'` is the canonical shorthand for 'start when the previous tween started'. Use it for parallel tweens; the explicit `'<=0'` form is rare.

Can I use position parameters with stagger?

Yes - the position parameter controls when the WHOLE stagger starts. Each child still spaces by the stagger amount. Combine them when you want the stagger group to overlap with the previous tween: `.from(items, { stagger: 0.05, ... }, '-=0.4')`.

Why is my '+=' position not adding time?

`+=` and `-=` are RELATIVE to the previous tween's END by default. If you want relative-to-start, prefix with `<`: `'<+=0.2'` is 0.2s after the previous tween STARTED. `'+=0.2'` (no `<`) is 0.2s after it ENDED. Easy mix-up.

Should I use position parameters or chained timelines?

Position parameters keep one timeline easy to control as a whole (play, reverse, scrub). Chained child timelines (`.add(childTl, position)`) help when one block of choreography is reusable - the child has its own internal sequencing, the parent just slots it at the right beat. For 5-10 tween animations, one timeline + position params is usually enough.

Timeline

Position parameter

Q: What's the difference between '<' and '<=0'?

They behave the same for the parallel case. `'<'` is the canonical shorthand for 'start when the previous tween started'. Use it for parallel tweens; the explicit `'<=0'` form is rare.

Q: Can I use position parameters with stagger?

Yes - the position parameter controls when the WHOLE stagger starts. Each child still spaces by the stagger amount. Combine them when you want the stagger group to overlap with the previous tween: `.from(items, { stagger: 0.05, ... }, '-=0.4')`.

Q: Why is my '+=' position not adding time?

`+=` and `-=` are RELATIVE to the previous tween's END by default. If you want relative-to-start, prefix with `<`: `'<+=0.2'` is 0.2s after the previous tween STARTED. `'+=0.2'` (no `<`) is 0.2s after it ENDED. Easy mix-up.

Q: Should I use position parameters or chained timelines?

Position parameters keep one timeline easy to control as a whole (play, reverse, scrub). Chained child timelines (`.add(childTl, position)`) help when one block of choreography is reusable - the child has its own internal sequencing, the parent just slots it at the right beat. For 5-10 tween animations, one timeline + position params is usually enough.

The position parameter is the second-to-last argument on any timeline `.to()` / `.from()` / `.set()` call. It controls WHERE on the timeline the tween starts relative to what came before - overlap, gap, at a label, at an absolute time. It's how you compose choreography that isn't just 'play these tweens in order'.

Updated June 2, 2026

Mechanics

How the position parameter works

Without a position parameter, each timeline tween starts when the previous one ends. The position parameter overrides that: you can start at an absolute time, relative to the previous tween's start/end, at a named label, or anywhere in between.

script.js

Vocabulary

Every position parameter form

'<' - start at the SAME time as the previous tween started (parallel)
'>' - start when the previous tween ends (default, only used to be explicit)
'<+=0.2' - 0.2s after the previous tween's start
'>-=0.3' - 0.3s before the previous tween's end (overlap)
'-=0.3' - shorthand for '>-=0.3' (overlap by 0.3s)
'+=0.2' - shorthand for '>+=0.2' (gap of 0.2s)
1.5 - absolute time on the timeline (start at 1.5s regardless of what came before)
'labelName' - start at a named label set with tl.addLabel('labelName')
'labelName-=0.1' - 0.1s before the label

When

Use the position parameter for

Overlapping tweens (panel slide-in + content fade-in starting partway through)
Triggering several tweens at the same beat (icon rotation + label change + ring pulse all at time X)
Adding gaps without inserting a separate empty tween
Building reusable choreography with named labels (open, settled, close)
Anywhere the sequencing matters more than the per-tween config

Alternatives

Use something else when

Truly sequential tweens (default behaviour) - omit the position parameter entirely
Many parallel tweens with identical timing - use gsap.to([el1, el2, ...]) with a stagger instead of position params on each
Tween-level start delay (no timeline) - use the delay property on the tween directly
Cross-timeline coordination - nest one timeline inside another with .add(childTl, position) rather than threading position params across separate timelines

In production

Used in these Annnimate components

The Multi Flip uses position params to overlap the outgoing card's exit with the incoming card's enter so the gallery never has a 'gap' frame
The Magnetic Button uses '<' to fire the label scramble at the same beat as the pointer-tracking pull
The Mega Menu uses named labels (open, panel-visible, closed) so the open/close timelines can reference the same beats independently
The Dual Scramble uses '-=0.2' overlap so the underline expand starts before the character scramble finishes, keeping the motion continuous

Used in components

See it running in production

Multi FlipA stack of cards that fans out from a messy pile into a neat grid as you scroll, each one starting overlapped at a random angle.

Magnetic ButtonThe button and its text gently pull toward your cursor and drift with it, so it feels like it's reaching for you.

Mega MenuOne dropdown that grows and shrinks to fit as you move between menu groups, opening from whichever side you came from.

Dual ScrambleText scrambles through a brand colour and then settles into its final colour.

FAQ

Common questions

When should I use labels vs numeric positions?: Use labels when the same beat is referenced by multiple tweens or by separate timelines. They make the choreography self-documenting and survive duration changes - if you slow down an earlier tween, the labeled beat shifts but anything anchored to the label follows. Use numeric positions for one-off overlap/gap fine-tuning.
What's the difference between '<' and '<=0'?: They behave the same for the parallel case. '<' is the canonical shorthand for 'start when the previous tween started'. Use it for parallel tweens; the explicit '<=0' form is rare.
Can I use position parameters with stagger?: Yes - the position parameter controls when the WHOLE stagger starts. Each child still spaces by the stagger amount. Combine them when you want the stagger group to overlap with the previous tween: .from(items, { stagger: 0.05, ... }, '-=0.4').
Why is my '+=' position not adding time?: += and -= are RELATIVE to the previous tween's END by default. If you want relative-to-start, prefix with <: '<+=0.2' is 0.2s after the previous tween STARTED. '+=0.2' (no <) is 0.2s after it ENDED. Easy mix-up.
Should I use position parameters or chained timelines?: Position parameters keep one timeline easy to control as a whole (play, reverse, scrub). Chained child timelines (.add(childTl, position)) help when one block of choreography is reusable - the child has its own internal sequencing, the parent just slots it at the right beat. For 5-10 tween animations, one timeline + position params is usually enough.

PreviousNested timelinesNested timelines are GSAP timelines added inside another timeline as a single, self-contained unit, so a whole sub-sequence can be positioned, delayed, sped up, or reversed as one object.Nextrepeat & repeatDelayrepeat and repeatDelay are GSAP special properties that loop a tween or timeline a set number of times, with an optional gap between each pass.

Related conceptsgsap.timeline()stagger yoyo ease-in-out