TransitionEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface TransitionEvent extends Event

Beschreibung

TransitionEvent ist der Ereignistyp für die vier Übergangs-Ereignisse transitionrun, transitionstart, transitionend und transitioncancel. Der Browser löst sie aus, wenn sich eine CSS-Eigenschaft mit definierter transition ändert. So können Sie in JavaScript genau auf den Zeitpunkt reagieren, zu dem eine Animation beginnt oder endet, statt mit setTimeout die Dauer zu schätzen.

Zusätzlich zu den geerbten Eigenschaften von Event bietet das Interface drei schreibgeschützte Eigenschaften:

propertyName (string): Name der CSS-Eigenschaft, deren Übergang das Ereignis ausgelöst hat, z. B. "opacity" oder "transform".
elapsedTime (number): Laufzeit des Übergangs in Sekunden zum Zeitpunkt des Ereignisses – ohne transition-delay.
pseudoElement (string): Name des Pseudo-Elements mit führendem :: (z. B. "::before") oder ein leerer String, wenn der Übergang auf dem Element selbst läuft.

Typische Einsatzfälle sind das Entfernen eines Elements aus dem DOM nach dem Ausblenden, das Verketten mehrerer Animationsschritte oder das Aufräumen von Zustandsklassen. Ereignisse werden pro animierter Eigenschaft einzeln ausgelöst – ändert ein Übergang opacity und transform, feuert transitionend zweimal. Außerdem bubbeln die Ereignisse, sodass auch Übergänge von Kind-Elementen beim Eltern-Listener ankommen.

Mit dem Konstruktor new TransitionEvent(type, options) lassen sich eigene Ereignisse erzeugen, etwa für Tests. Solche synthetischen Ereignisse lösen aber keinen echten Übergang aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"transitionend"`, `"transitionstart"`, `"transitionrun"` oder `"transitioncancel"` (nur beim Konstruktor).
$options	TransitionEventInit	{}	Optionales Objekt mit den `EventInit`-Feldern (`bubbles`, `cancelable`, `composed`) sowie `propertyName` (Standard `""`), `elapsedTime` (Standard `0`) und `pseudoElement` (Standard `""`).

Rückgabewert

Typ

TransitionEvent

Beschreibung

Der Konstruktor gibt ein neues TransitionEvent-Objekt zurück. Dieses können Sie mit dispatchEvent() an ein Element senden.

Beispiele

Element nach dem Ausblenden entfernen

// CSS: .toast { transition: opacity 0.4s ease; } .toast.hidden { opacity: 0; }
const toast = document.querySelector('.toast');

const onEnd = (event) => {
  // Nur auf den opacity-Übergang des Elements selbst reagieren
  if (event.target !== toast || event.propertyName !== 'opacity') return;
  console.log(`Fertig nach ${event.elapsedTime}s`);
  toast.remove();
  toast.removeEventListener('transitionend', onEnd);
};

toast.addEventListener('transitionend', onEnd);
toast.classList.add('hidden');

Fertig nach 0.4s

Übergang als Promise abwarten (inkl. Abbruch)

const waitForTransition = (el, property) =>
  new Promise((resolve, reject) => {
    const done = (event) => {
      if (event.target !== el || event.propertyName !== property) return;
      el.removeEventListener('transitionend', done);
      el.removeEventListener('transitioncancel', done);
      event.type === 'transitionend' ? resolve(event) : reject(new Error('abgebrochen'));
    };
    el.addEventListener('transitionend', done);
    el.addEventListener('transitioncancel', done);
  });

const panel = document.querySelector('#panel');
panel.style.transition = 'transform 300ms';

const run = async () => {
  panel.style.transform = 'translateX(200px)';
  try {
    const e = await waitForTransition(panel, 'transform');
    console.log('Schritt 1 fertig:', e.propertyName);
    panel.style.transform = 'translateX(0)';
  } catch (err) {
    console.warn('Übergang', err.message);
  }
};
run();

Schritt 1 fertig: transform

Alle Phasen protokollieren über on-Properties

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

const log = (e) => console.log(e.type, e.propertyName, e.elapsedTime, e.pseudoElement || '(Element)');

box.ontransitionrun = log;
box.ontransitionstart = log;   // nach Ablauf von transition-delay
box.ontransitionend = log;
box.ontransitioncancel = log;

box.classList.toggle('expanded');

transitionrun width 0 (Element) transitionstart width 0 (Element) transitionend width 0.5 (Element)

Synthetisches Ereignis erzeugen (z. B. für Tests)

const el = document.createElement('div');
el.addEventListener('transitionend', (e) => {
  console.log(e instanceof TransitionEvent, e.propertyName, e.elapsedTime);
});

const evt = new TransitionEvent('transitionend', {
  bubbles: true,
  propertyName: 'opacity',
  elapsedTime: 0.25
});
el.dispatchEvent(evt);

true opacity 0.25

// Wichtig · Fallstricke

Kein Ereignis ohne echten Übergang: transitionend feuert nicht, wenn sich der Wert nicht ändert, die Dauer 0s ist, die Eigenschaft nicht animierbar ist (z. B. display, außer mit transition-behavior: allow-discrete) oder das Element vorher entfernt bzw. auf display: none gesetzt wird. Wer auf das Ende warten muss, sollte zusätzlich transitioncancel abfangen oder einen Sicherheits-Timeout einbauen.
Mehrfachauslösung: Pro animierter Eigenschaft kommt ein eigenes Ereignis. Kurzschreibweisen wie border oder padding erzeugen Ereignisse für die einzelnen Langform-Eigenschaften (z. B. padding-left). Deshalb immer propertyName prüfen.
Bubbling: Übergänge von Kind-Elementen erreichen auch Listener am Eltern-Element. Mit event.target === element filtern.
elapsedTime enthält nicht den transition-delay. Bei transitioncancel steht dort die bis zum Abbruch vergangene Zeit.
Kompatibilität: transitionend wird seit Jahren überall unterstützt. transitionrun, transitionstart und transitioncancel gibt es erst in neueren Browsern (Chrome 87+, Safari 13.1+, Firefox 53+). Präfixe wie webkitTransitionEnd brauchen nur noch sehr alte Browser.
Für eine programmatische Steuerung (Pausieren, Abfragen des Fortschritts) eignet sich die Web Animations API mit element.getAnimations() und animation.finished oft besser.

Siehe auch

Event PageTransitionEvent AnimationEvent CompositionEvent XRSessionEvent