Animation.pause() — Methode · JavaScript-Referenz

Signatur

Animation.prototype.pause()

Beschreibung

Die Methode pause() hält eine laufende Animation an. Die aktuelle Zeit (currentTime) wird eingefroren, das Element bleibt im Zwischenzustand stehen. Ein anschließender Aufruf von play() setzt die Animation genau an dieser Stelle fort, statt sie neu zu starten.

Typische Einsatzfälle sind Pausieren-Schaltflächen für Animationen, das Anhalten bei mouseenter (z. B. bei Laufbändern oder Karussells), das Anhalten, wenn ein Element nicht sichtbar ist, oder das Pausieren einer Animation, um sie anschließend per currentTime manuell zu steuern (etwa scroll-gesteuert).

Wird pause() auf einer noch nicht gestarteten oder bereits beendeten Animation aufgerufen, wird sie in den Zustand "paused" versetzt. Ist die Animation noch im Leerlauf (playState === "idle"), wird sie am Anfang (bzw. bei negativer playbackRate am Ende) pausiert. Die Pause wird asynchron wirksam: Bis sie greift, ist pending auf true gesetzt; das Promise animation.ready wird erfüllt, sobald die Pause tatsächlich aktiv ist.

Beispiele

Animation starten und per Button pausieren/fortsetzen

const box = document.querySelector('#box');
const toggle = document.querySelector('#toggle');

const animation = box.animate(
  [{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }],
  { duration: 2000, iterations: Infinity }
);

toggle.addEventListener('click', () => {
  if (animation.playState === 'running') {
    animation.pause();
    toggle.textContent = 'Fortsetzen';
  } else {
    animation.play();
    toggle.textContent = 'Pausieren';
  }
});

Laufband beim Überfahren mit der Maus anhalten

const ticker = document.querySelector('.ticker');

const scroll = ticker.animate(
  [{ transform: 'translateX(100%)' }, { transform: 'translateX(-100%)' }],
  { duration: 10000, iterations: Infinity }
);

ticker.addEventListener('mouseenter', () => scroll.pause());
ticker.addEventListener('mouseleave', () => scroll.play());

Auf das Wirksamwerden der Pause warten

const el = document.querySelector('.fade');
const anim = el.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 3000 });

setTimeout(async () => {
  anim.pause();
  console.log(anim.pending, anim.playState);
  await anim.ready;
  console.log(`Pausiert bei ${Math.round(anim.currentTime)} ms`);
}, 1000);

true "paused" Pausiert bei 1000 ms

Animation pausieren und manuell per Scroll steuern

const bar = document.querySelector('.progress');
const anim = bar.animate(
  [{ width: '0%' }, { width: '100%' }],
  { duration: 1000, fill: 'both' }
);
anim.pause(); // nicht selbst laufen lassen

window.addEventListener('scroll', () => {
  const max = document.documentElement.scrollHeight - innerHeight;
  anim.currentTime = (scrollY / max) * 1000;
});

// Wichtig · Fallstricke

Asynchron: Nach pause() ist die Pause nicht sofort gerendert; pending ist zunächst true. Wer exakte Werte von currentTime benötigt, sollte await animation.ready verwenden.
Kein finish-Ereignis: Eine pausierte Animation feuert kein finish-Ereignis, und animation.finished bleibt unerfüllt, bis sie weiterläuft und endet.
Ausnahme: Wirft einen InvalidStateError (DOMException), wenn die Animation unendlich lang ist (iterations: Infinity), die playbackRate negativ ist und currentTime ungesetzt ist – dann kann kein Endpunkt zum Pausieren bestimmt werden.
Kein Entfernen: pause() hält nur an. Um die Wirkung einer Animation vollständig zu entfernen, nutze cancel(); zum Springen ans Ende finish().
CSS-Animationen: Auch per document.getAnimations() ermittelte CSS-Animationen und -Transitions lassen sich so pausieren; das überschreibt ggf. animation-play-state.
Kompatibilität: In allen aktuellen Browsern (Chrome, Edge, Firefox, Safari) verfügbar; ältere Safari-Versionen (< 13.1) unterstützen die Web Animations API nur eingeschränkt.

Siehe auch

Animation.play() Animation.cancel() Animation.finish() Animation.playState Animation.ready Animation.currentTime Element.animate() Animation