new TransitionEvent() — Methode · JavaScript-Referenz

Signatur

new TransitionEvent(type, options)

Beschreibung

Der Konstruktor TransitionEvent() erzeugt ein synthetisches Ereignisobjekt vom Typ TransitionEvent. Normalerweise erzeugt der Browser solche Ereignisse selbst, wenn eine CSS-Transition eingeplant wird (transitionrun), beginnt (transitionstart), endet (transitionend) oder abgebrochen wird (transitioncancel).

Den Konstruktor braucht man vor allem in Tests (z. B. mit jsdom, Jest oder Playwright) und für Fallbacks: Code, der auf transitionend wartet, bleibt sonst hängen, wenn gar keine Transition läuft (etwa bei prefers-reduced-motion oder display: none). Mit dispatchEvent() kann man das Ereignis dann selbst auslösen.

Zusätzlich zu den Event-Optionen (bubbles, cancelable, composed) nimmt das Options-Objekt die transitionsspezifischen Felder propertyName, elapsedTime und pseudoElement an. Diese stehen danach als schreibgeschützte Eigenschaften am Ereignis zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"transitionend"`, `"transitionstart"`, `"transitionrun"` oder `"transitioncancel"`. Groß-/Kleinschreibung wird beachtet.
$options	TransitionEventInit	{}	Optionales Objekt mit folgenden Feldern: `propertyName` (`string`, Standard `""`): Name der CSS-Eigenschaft der Transition, z. B. `"opacity"`. `elapsedTime` (`number`, Standard `0`): Laufzeit der Transition in Sekunden (ohne `transition-delay`). `pseudoElement` (`string`, Standard `""`): Pseudo-Element, beginnend mit `::`, z. B. `"::before"`. `bubbles`, `cancelable`, `composed` (`boolean`, Standard `false`): geerbt von `EventInit`.

Rückgabewert

Typ

TransitionEvent

Beschreibung

Ein neues TransitionEvent-Objekt mit den übergebenen Werten. Es ist noch nicht ausgelöst, das erledigt erst dispatchEvent().

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

const event = new TransitionEvent('transitionend', {
  propertyName: 'opacity',
  elapsedTime: 0.3,
  bubbles: true
});

console.log(event.type, event.propertyName, event.elapsedTime, event.bubbles);
console.log(event instanceof Event);
console.log(event.isTrusted);

transitionend opacity 0.3 true true false

Fallback: transitionend selbst auslösen, wenn keine Animation läuft

const fadeOut = (el) => new Promise((resolve) => {
  const onEnd = (e) => {
    if (e.target !== el || e.propertyName !== 'opacity') return;
    el.removeEventListener('transitionend', onEnd);
    resolve();
  };
  el.addEventListener('transitionend', onEnd);
  el.style.opacity = '0';

  // Bei reduzierter Bewegung läuft keine Transition, also selbst auslösen
  if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
    el.dispatchEvent(new TransitionEvent('transitionend', {
      propertyName: 'opacity',
      bubbles: true
    }));
  }
});

const box = document.querySelector('.toast');
await fadeOut(box);
box.remove();
console.log('Toast entfernt');

Toast entfernt

Unit-Test: Handler für transitionend prüfen

const panel = document.createElement('div');
document.body.append(panel);

let closed = false;
panel.addEventListener('transitionend', (e) => {
  if (e.propertyName === 'height') closed = true;
});

// Andere Eigenschaft: Handler soll sie ignorieren
panel.dispatchEvent(new TransitionEvent('transitionend', { propertyName: 'color' }));
console.log(closed);

panel.dispatchEvent(new TransitionEvent('transitionend', { propertyName: 'height', elapsedTime: 0.25 }));
console.log(closed);

false true

// Wichtig · Fallstricke

Einheit: elapsedTime wird in Sekunden angegeben, nicht in Millisekunden, also 0.3 und nicht 300.
Kein echtes Ereignis: Selbst erzeugte Ereignisse haben isTrusted === false und starten keine Transition. Sie rufen nur die registrierten Listener auf.
Bubbling: Vom Browser ausgelöste transitionend-Ereignisse steigen im DOM auf (bubbles: true). Beim Konstruktor ist der Standard false. Wer Ereignis-Delegation nachbilden will, muss bubbles: true selbst setzen.
Kindelemente: Weil die Ereignisse aufsteigen, kommen auch Transitionen von Kindelementen beim Listener an. Deshalb immer e.target und e.propertyName prüfen.
Kompatibilität: Der Konstruktor wird von allen modernen Browsern unterstützt. Alte WebKit-Versionen kannten nur webkitTransitionEnd, und im Internet Explorer gab es keinen Konstruktor, dort nur document.createEvent('TransitionEvent'). In jsdom fehlt TransitionEvent je nach Version. Dann hilft ein allgemeines Event mit nachträglich gesetztem propertyName.
Ohne new aufgerufen wirft der Konstruktor einen TypeError.

Siehe auch

TransitionEvent EventTarget.prototype.dispatchEvent() new PageTransitionEvent() new AnimationEvent() new CompositionEvent()