Animation: remove — Ereignis · JavaScript-Referenz

Signatur

animation.addEventListener("remove", handler)

Beschreibung

Das Ereignis remove des Animation-Interfaces wird ausgelöst, wenn der Browser eine Animation automatisch entfernt. Das passiert, wenn viele Animationen auf dasselbe Element wirken: Jede Animation mit fill: "forwards" oder fill: "both" würde sonst dauerhaft im Speicher bleiben. Das wird zum Beispiel zum Problem, wenn bei jeder Mausbewegung eine neue Animation erzeugt wird.

Eine Animation wird nur entfernt, wenn alle diese Bedingungen erfüllt sind:

Sie ist beendet (playState === "finished") oder wird ohnehin nicht mehr abgespielt.
Sie hat einen Füllmodus (forwards oder both), wirkt also nach dem Ende weiter.
Sie hängt an einer Dokument-Zeitleiste (document.timeline).
Jede Eigenschaft, die sie animiert, wird von neueren Animationen auf demselben Zielelement vollständig überschrieben.
Sie wurde nicht mit persist() dauerhaft gemacht.

Danach steht animation.replaceState auf "removed". Das Ereignis ist ein AnimationPlaybackEvent mit den Eigenschaften currentTime und timelineTime. Es steigt nicht auf (bubbles nicht) und lässt sich nicht abbrechen. Den Handler registrierst du entweder mit addEventListener("remove", …) oder über die Eigenschaft animation.onremove.

Wofür ist das gut? Zum Beispiel für die Fehlersuche oder um den Endzustand einer entfernten Animation mit commitStyles() fest in das style-Attribut zu schreiben. Soll eine Animation gar nicht entfernt werden, rufst du animation.persist() auf.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"remove"`.
$handler Pflicht	(event: AnimationPlaybackEvent) => void		Callback, der beim Entfernen aufgerufen wird. `event.target` ist die entfernte `Animation`, dazu gibt es `event.currentTime` und `event.timelineTime`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie bei `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein AnimationPlaybackEvent.

Beispiele

Automatisches Entfernen beim Mausverfolgen beobachten

const dot = document.querySelector('#dot');
let removedCount = 0;

document.addEventListener('mousemove', (e) => {
  // Jede Bewegung erzeugt eine neue, füllende Animation
  const anim = dot.animate(
    { transform: `translate(${e.clientX}px, ${e.clientY}px)` },
    { duration: 300, fill: 'forwards' }
  );

  anim.addEventListener('remove', (event) => {
    removedCount++;
    console.log(`Entfernt: ${removedCount}, replaceState: ${event.target.replaceState}`);
  });
});

Entfernt: 1, replaceState: removed Entfernt: 2, replaceState: removed …

Endzustand über onremove sichern

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

const first = box.animate({ opacity: [1, 0.5] }, { duration: 200, fill: 'forwards' });

first.onremove = (event) => {
  // commitStyles() funktioniert auch bei bereits entfernten Animationen
  event.target.commitStyles();
  console.log('Stil festgeschrieben:', box.style.opacity);
};

// Die zweite Animation überdeckt opacity vollständig
first.finished.then(() => {
  box.animate({ opacity: [0.5, 0.2] }, { duration: 200, fill: 'forwards' });
});

Stil festgeschrieben: 0.5

Entfernen mit persist() verhindern und Listener abmelden

const el = document.querySelector('.panel');
const anim = el.animate({ transform: ['scale(1)', 'scale(1.2)'] }, { duration: 500, fill: 'forwards' });

const onRemove = () => console.log('Animation wurde entfernt');
anim.addEventListener('remove', onRemove);

// Diese Animation soll erhalten bleiben
anim.persist();
console.log(anim.replaceState);

// Listener wird nicht mehr gebraucht
anim.removeEventListener('remove', onRemove);

persisted

// Wichtig · Fallstricke

Nur füllende Animationen: Animationen ohne fill: "forwards" oder "both" werden nie automatisch entfernt. Bei ihnen wird remove also nie ausgelöst.
Vollständige Überdeckung nötig: Überschreibt eine neuere Animation nur einen Teil der animierten Eigenschaften (z. B. nur opacity, nicht aber transform), bleibt die ältere Animation bestehen.
Zeitpunkt: Entfernt wird beim nächsten Aktualisieren der Animationen, also meist im nächsten Frame, nicht sofort. Das Ereignis kommt deshalb asynchron.
Kein Abbruch: preventDefault() hat keine Wirkung. Um das Entfernen zu verhindern, musst du persist() aufrufen, bevor die Animation entfernt wird. Auf eine schon entfernte Animation angewendet, stellt persist() sie wieder her.
Speicher: Wer viele Animationen mit persist() dauerhaft macht, verliert den Speicherschutz. Besser ist meist commitStyles() mit anschließendem cancel().
CSS-Animationen und -Übergänge: Auch CSSAnimation- und CSSTransition-Objekte können das Ereignis erhalten, wenn sie die Bedingungen erfüllen.
Kompatibilität: Unterstützt in allen modernen Browsern (Chrome/Edge 84+, Firefox 75+, Safari 13.1+). Ältere Browser entfernen keine Animationen automatisch und lösen das Ereignis nicht aus.

Siehe auch

Animation Animation.prototype.persist() Animation.prototype.commitStyles() Animation.replaceState AnimationPlaybackEvent Element.prototype.animate()