Timeline

timeScale

timeScale is a GSAP method that changes the playback rate of a tween or timeline while it is running: `timeScale(2)` plays it at double speed, `timeScale(0.5)` at half speed, and `timeScale(1)` is normal. You call it on a live animation to speed it up, slow it down, or ramp the rate smoothly, with no need to rebuild the tween or touch any per-step duration.

Updated June 30, 2026

Mechanics

How timeScale works

timeScale is a getter and a setter on the same method. Pass a number to set the rate, call it with no arguments to read the current rate. The value is a multiplier on time: at 2 every second of the animation plays in half a second, at 0.25 it stretches to four times as long. It applies to the whole animation including every nested tween and child timeline, so one call retimes a multi-step sequence at once.

script.js

Because timeScale is just a property, you can tween it. Animating the rate instead of setting it gives a smooth ramp rather than an instant jump, which is how a looping marquee eases down on hover instead of snapping to a stop.

script.js

timeScale does not reverse direction

Setting a faster or slower rate never flips which way the playhead moves. Direction is controlled by play() and reverse(). timeScale controls how fast it runs in whichever direction it is going, so tl.timeScale(2).reverse() plays backward at double speed.
When

Use it for

  • Eased speed ramps on a looping animation, like slowing a marquee to a crawl on hover and bringing it back on leave
  • Resetting a loop's rate after an inertia drag, then handing direction to play() or reverse()
  • Retiming a whole sequence in one call instead of editing the duration on every child tween
  • A global slow-motion or instant-finish via gsap.globalTimeline.timeScale(), the standard prefers-reduced-motion shortcut in this codebase
  • Dev-time inspection, dropping the rate to 0.1 to watch a fast choreography frame by frame
script.js
Alternatives

Use something else when

  • You want the rate bound to scroll position, not a fixed multiplier, use ScrollTrigger scrub so the scrollbar drives the playhead
  • You only need to flip direction, call reverse() or play(), not a negative number
  • The animation's natural length is wrong everywhere, set the right duration at build time instead of correcting it at runtime
  • You need to jump to a specific point rather than change speed, use seek() or progress()
  • You are retiming a cover or preloader to a target length, the Kit duration contract does this with tl.timeScale(tl.duration() / target) so a value of 0 means natural pace
In production

Used in these Annnimate components

  • The Marquee runs on an infinite-repeating timeline and calls tl.timeScale(1) to reset its rate after an inertia drag, then play() or reverse() to pick the scroll direction from the throw
  • The Counter rolls every digit on one timeline, so a single timeScale() call can retime the whole count, fast on first paint and slow on a hero number, without rewriting any per-digit duration

Why runtime retiming matters

GSAP runs on about 2.2% of all websites as of June 2026 (w3techs), roughly 2.15M weekly npm installs (npmtrends, 2026). timeScale is the method those sites reach for when an animation needs to change pace after it is already playing, since rebuilding a live tween mid-flight is the thing it exists to avoid. Source: GSAP timeline docs, gsap.com/docs/v3.
Used in components

See it running in production

Infinite MarqueeA row of content that scrolls on its own, sideways or up and down, and you can grab it to scrub through and let go to keep it going.CounterA number that counts up as you scroll to it, either rolling like an odometer with each digit spinning on its own, or ticking up smoothly.
FAQ

Common questions

How do I speed up a GSAP timeline at runtime?
Call tl.timeScale(2) for double speed or any multiplier you want. It takes effect immediately on the running timeline and scales every child tween with it. Call tl.timeScale() with no argument to read the current rate back.
Does timeScale reverse the animation?
No. timeScale only changes how fast the playhead moves, not which way. Use reverse() to play backward and play() to go forward again. The rate you set is honored in both directions, so tl.timeScale(2).reverse() runs backward at double speed.
What's the difference between timeScale and changing duration?
duration is set when you build a tween and defines its natural length. timeScale is a runtime multiplier on top of that, so you can speed up or slow down an animation that is already playing without rebuilding it. Change duration when the length is wrong everywhere, use timeScale when you need to retime live.
How do I smoothly ramp timeScale instead of it jumping?
Tween the property: gsap.to(tl, { timeScale: 0.25, duration: 0.4, ease: "expo.out" }). Because timeScale is an ordinary property, GSAP can animate it, which gives you an eased acceleration or deceleration instead of an instant rate change. This is the pattern behind a marquee that eases to a near-stop on hover.
How do I slow down or stop all GSAP animations at once?
Set the rate on the global timeline: gsap.globalTimeline.timeScale(0.2) slows everything to a fifth, gsap.globalTimeline.timeScale(20) finishes everything almost instantly. The instant version is the common prefers-reduced-motion handling, since it lets motion resolve to its end state without ripping out every tween.
PreviousTimeline labelsTimeline labels are named time positions you attach to a GSAP timeline with addLabel(), then reference by name to place tweens, seek the playhead, or start playback.Nextyoyoyoyo is a GSAP repeat modifier that makes each odd repeat play in reverse.
Related conceptsgsap.timeline()Scrubstagger