How to Control Animation Playback in Anime.js: Play, Pause, Restart, and Reverse

Anime.js exposes a unified playback API through the Timer class, providing play(), pause(), reverse(), and restart() methods that work identically across animations, timelines, and Web Animation API wrappers.

All animation objects created via anime(), anime.timeline(), or anime.waapi() inherit from the core Timer class defined in src/timer/timer.js. This shared inheritance means you can control animation playback using the same four methods regardless of which API entry point you use.

The Timer Foundation

Every animatable object in Anime.js extends the Timer class, which manages the internal state flags _reversed, paused, and _autoplay. The playback methods are thin wrappers around these flags and the generic resume() and seek() logic.

According to the source code in src/timer/timer.js, the Timer class serves as the base implementation for:

• JSAnimation (src/animation/animation.js)
• Timeline (src/timeline/timeline.js)
• WAAPIAnimation (src/waapi/waapi.js)

This design ensures consistent behavior whether you are controlling a single tween or a complex sequence.

Playback Methods Explained

play()

The play() method starts or resumes an animation from its current position. If the animation was previously reversed, it first flips the direction by calling alternate() before invoking resume().

In src/timer/timer.js (lines 40-44), the implementation is:

play() {
  if (this._reversed) this.alternate();
  return this.resume();
}

Use this method to begin an animation that was created with autoplay: false or to resume one that was previously paused.

pause()

The pause() method immediately stops the animation at its current time without resetting progress. It simply sets the paused state flag to true, preventing the engine from invoking the tick callback for this timer.

The implementation in src/timer/timer.js (lines 371-376) checks the current state before pausing:

pause() {
  if (this.paused) return this;
  this.paused = true;
  // ... engine deregistration logic
  return this;
}

reverse()

The reverse() method toggles the playback direction. When the animation is not already reversed, it calls the internal alternate() method, which flips the _reversed flag and seeks to the opposite side of the current loop.

As implemented in src/timer/timer.js (lines 47-51):

reverse() {
  if (!this._reversed) this.alternate();
  return this.resume();
}

This method is particularly useful for creating bidirectional interactions where elements animate forward on hover and backward on mouse leave.

restart()

The restart() method resets the timer to the beginning (or to the end, if currently reversed) and immediately starts playing. It chains reset(true) with play() to clear all internal progress including the completed flag.

From src/timer/timer.js (lines 400-404):

restart() {
  return this.reset(true).play();
}

Use restart() when you need to replay an animation from its initial state, ignoring any current pause or progress position.

Practical Code Examples

Basic Animation Control

Create an animation with autoplay: false to enable manual playback control:

const box = anime({
  targets: '.box',
  translateX: 250,
  duration: 1000,
  autoplay: false,
});

// Control playback programmatically
box.play();      // Starts moving right
box.pause();     // Stops at current position
box.reverse();   // Plays backward from current position
box.restart();   // Resets to start and plays immediately

Timeline Playback

Timelines inherit the same playback methods from Timer, allowing you to control entire sequences as a single unit:

const tl = anime.timeline({
  autoplay: false,
  loop: 2,
});

tl.add({
  targets: '.box',
  translateX: 250,
  duration: 1000,
}).add({
  targets: '.circle',
  scale: 2,
  duration: 500,
}, '-=500');

// Control the entire sequence
tl.play();     // Start all tweens
tl.pause();    // Pause all tweens simultaneously
tl.reverse();  // Flip direction for remaining loops
tl.restart();  // Reset to first tween and play

Web Animation API Wrapper

The anime.waapi() method returns a WAAPIAnimation instance that proxies playback calls to its internal Timer implementation:

const waapiAnim = anime.waapi({
  targets: document.querySelector('.box'),
  keyframes: [
    { transform: 'translateX(0px)' },
    { transform: 'translateX(250px)' }
  ],
  duration: 1000,
  autoplay: false,
});

waapiAnim.play();    // Starts native animation
waapiAnim.pause();   // Pauses native animation
waapiAnim.reverse(); // Runs backward
waapiAnim.restart(); // Resets and plays from start

Summary

• Unified API: All Anime.js objects (anime(), anime.timeline(), anime.waapi()) inherit playback methods from the Timer class in src/timer/timer.js.
• Four Core Methods: Use play() to start/resume, pause() to stop, reverse() to flip direction, and restart() to reset and play.
• State Management: Playback relies on internal flags (_reversed, paused) managed by the Timer base class.
• Consistent Behavior: Whether controlling a single tween or a complex timeline, the same method signatures and behaviors apply across all animation types.

Frequently Asked Questions

How do I prevent an animation from playing immediately when created?

Set the autoplay option to false when creating the animation. This allows you to store the animation instance and call play() later when needed, such as in response to a user interaction.

What is the difference between reverse() and playing with a negative playbackRate?

The reverse() method toggles the _reversed state flag and calls alternate(), which seeks to the mirrored time position within the current loop iteration. This is distinct from changing playbackRate, which affects speed but does not automatically handle loop boundaries or direction flags managed by alternate().

Can I pause and resume a timeline midway through?

Yes. Because Timeline extends Timer, calling pause() on a timeline instance sets the paused flag to true for the entire sequence. Calling play() later resumes all child animations from their current positions simultaneously.

Where are the playback methods actually implemented?

The implementation resides in src/timer/timer.js. Classes like JSAnimation (src/animation/animation.js), Timeline (src/timeline/timeline.js), and WAAPIAnimation (src/waapi/waapi.js) inherit these methods automatically through class extension, ensuring consistent API behavior across all animation types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}