AnimationEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface AnimationEvent extends Event

Beschreibung

AnimationEvent ist der Ereignistyp, den der Browser bei CSS-Animationen (@keyframes + animation) auslöst. Es gibt vier Ereignisse: animationstart, animationiteration, animationend und animationcancel. Mit ihnen kann JavaScript auf den Verlauf einer rein in CSS definierten Animation reagieren, z. B. ein Element nach einer Ausblend-Animation aus dem DOM entfernen oder eine Folgeanimation starten.

Zusätzlich zu den geerbten Eigenschaften von Event bietet das Interface drei nur lesbare Eigenschaften:

animationName – Name der @keyframes-Regel, die das Ereignis ausgelöst hat.
elapsedTime – Laufzeit der Animation in Sekunden zum Zeitpunkt des Ereignisses (ohne Zeit, in der die Animation pausiert war; bei animationstart normalerweise 0, bei negativem animation-delay entsprechend positiv).
pseudoElement – z. B. "::before", wenn die Animation auf einem Pseudo-Element läuft, sonst ein leerer String.

Die Ereignisse blubbern (bubbles), daher eignet sich Ereignisdelegation: Ein Listener auf einem Container empfängt Animationsereignisse aller Kindelemente. Über den Konstruktor new AnimationEvent(type, init) lassen sich Ereignisse auch künstlich erzeugen, etwa für Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses beim Konstruktor-Aufruf, z. B. `"animationstart"`, `"animationiteration"`, `"animationend"` oder `"animationcancel"`.
$options	AnimationEventInit	{}	Optionales Objekt mit `animationName` (string, Standard `""`), `elapsedTime` (number, Standard `0`), `pseudoElement` (string, Standard `""`) sowie den `EventInit`-Feldern `bubbles`, `cancelable`, `composed`.

Rückgabewert

Typ

AnimationEvent

Beschreibung

Beim Konstruktor eine neue AnimationEvent-Instanz; in Ereignis-Handlern das vom Browser übergebene Ereignisobjekt.

Beispiele

Element nach Ausblend-Animation entfernen

// CSS: .fade-out { animation: fadeOut 0.4s forwards; }
//      @keyframes fadeOut { to { opacity: 0; } }
const toast = document.querySelector('.toast');

toast.addEventListener('animationend', (event) => {
  if (event.animationName !== 'fadeOut') return;
  console.log(`${event.animationName} fertig nach ${event.elapsedTime}s`);
  toast.remove();
}, { once: true });

toast.classList.add('fade-out');

fadeOut fertig nach 0.4s

Alle vier Animationsereignisse per Delegation protokollieren

const list = document.querySelector('#items');

const log = (event) => {
  const target = event.target.id || event.target.tagName;
  const pseudo = event.pseudoElement ? ` ${event.pseudoElement}` : '';
  console.log(`${event.type}: ${event.animationName} auf ${target}${pseudo} (${event.elapsedTime.toFixed(2)}s)`);
};

['animationstart', 'animationiteration', 'animationend', 'animationcancel']
  .forEach((type) => list.addEventListener(type, log));

animationstart: pulse auf item-1 (0.00s) animationiteration: pulse auf item-1 (1.00s) animationend: pulse auf item-1 (2.00s)

on-Property verwenden und wieder entfernen

const box = document.querySelector('.box');
let runden = 0;

box.onanimationiteration = (event) => {
  runden += 1;
  console.log(`Runde ${runden} von ${event.animationName}`);
  if (runden === 3) {
    box.style.animationPlayState = 'paused';
    box.onanimationiteration = null; // Handler entfernen
  }
};

Runde 1 von spin Runde 2 von spin Runde 3 von spin

Ereignis künstlich erzeugen (z. B. für Tests)

const el = document.createElement('div');

el.addEventListener('animationend', (e) => {
  console.log(e instanceof AnimationEvent, e.animationName, e.elapsedTime);
});

const evt = new AnimationEvent('animationend', {
  animationName: 'slideIn',
  elapsedTime: 1.5,
  bubbles: true
});
el.dispatchEvent(evt);

true slideIn 1.5

// Wichtig · Fallstricke

Endet nie? Bei animation-iteration-count: infinite wird animationend nie ausgelöst. Ebenso fehlt animationend, wenn die Animation vorher entfernt wird (z. B. display: none oder Klasse entfernt) – dann feuert stattdessen animationcancel.
Dauer 0: Wird die Animation per prefers-reduced-motion auf 0s gesetzt, feuern animationstart und animationend trotzdem; bei animation: none dagegen gar nichts. Code, der auf animationend wartet, sollte daher eine Rückfallebene (Timeout) haben.
Bubbling: Da die Ereignisse blubbern, empfängt ein Listener auch Animationen von Kindelementen – immer event.target bzw. event.animationName prüfen.
elapsedTime ist in Sekunden, nicht Millisekunden, und bei animationiteration nicht zwingend ganzzahlig exakt.
Für CSS-Transitions gibt es das separate TransitionEvent; per Web Animations API (element.animate()) erzeugte Animationen lösen keine AnimationEvents aus – dort Animation.finished bzw. onfinish nutzen.
Kompatibilität: In allen aktuellen Browsern ohne Präfix verfügbar; animationcancel und pseudoElement kamen später (Safari/Chrome erst in neueren Versionen). Sehr alte WebKit-Versionen benötigten webkitAnimationEnd.

Siehe auch

Event Animation Element.prototype.animate() AnimationEffect MutationEvent