CSSTransition — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSTransition extends Animation

Beschreibung

CSSTransition ist eine Unterklasse von Animation aus der Web Animations API. Wenn der Browser eine CSS-Transition startet, weil sich ein Wert ändert, für den transition gesetzt ist, legt er automatisch ein CSSTransition-Objekt an. Einen öffentlichen Konstruktor gibt es nicht. Die Objekte bekommt man über Element.prototype.getAnimations() oder document.getAnimations().

Weil die Klasse von Animation erbt, stehen alle bekannten Mitglieder zur Verfügung: play(), pause(), reverse(), finish(), cancel(), currentTime, playbackRate, effect sowie die Promises finished und ready. Dazu kommt nur eine eigene Eigenschaft: transitionProperty. Sie ist schreibgeschützt und enthält den Namen der CSS-Eigenschaft, die überblendet wird, z. B. "opacity" oder "background-color".

Typische Anwendungsfälle:

Auf das Ende einer bestimmten Transition warten, mit await animation.finished statt transitionend.
Transitionen in Tests oder bei prefers-reduced-motion sofort abschließen.
Eine Transition anhalten oder per currentTime an eine bestimmte Stelle springen, etwa für Scrubbing oder Fehlersuche.
Transitionen von CSS-Animationen (CSSAnimation) und Skript-Animationen per instanceof unterscheiden.

Parameter

Name	Typ	Default	Beschreibung
$transitionProperty	string		Schreibgeschützte Instanz-Eigenschaft (kein Konstruktor-Parameter). Enthält den Namen der überblendeten CSS-Eigenschaft als Longhand, z. B. `"margin-left"` statt `"margin"`.

Rückgabewert

Typ

CSSTransition

Beschreibung

Instanzen entstehen nur durch den Browser und werden von getAnimations() zurückgegeben. Mit new lassen sie sich nicht erzeugen.

Beispiele

Laufende Transitionen eines Elements auflisten

// CSS: .box { transition: opacity 1s, transform 0.5s; }
const box = document.querySelector('.box');

// Stilwerte ändern, damit die Transitionen starten
box.style.opacity = '0.2';
box.style.transform = 'translateX(100px)';

// getAnimations() berechnet die Stile neu, deshalb gibt es die Transitionen hier schon
const transitions = box
  .getAnimations()
  .filter((anim) => anim instanceof CSSTransition);

for (const t of transitions) {
  console.log(t.transitionProperty, t.playState);
}

opacity running transform running

Auf das Ende einer bestimmten Transition warten

const fadeOut = async (el) => {
  el.style.opacity = '0';

  const opacityTransition = el
    .getAnimations()
    .find((a) => a instanceof CSSTransition && a.transitionProperty === 'opacity');

  if (opacityTransition) {
    try {
      await opacityTransition.finished;
    } catch {
      // Transition wurde abgebrochen (z. B. durch einen neuen Stilwert)
      return;
    }
  }
  el.remove();
  console.log('Element entfernt');
};

fadeOut(document.querySelector('.toast'));

Element entfernt

Transitionen bei reduzierter Bewegung sofort abschließen

const skipTransitions = (root = document) => {
  const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
  if (!reduce) return 0;

  const transitions = root
    .getAnimations()
    .filter((a) => a instanceof CSSTransition);

  transitions.forEach((t) => t.finish());
  return transitions.length;
};

document.querySelector('.menu').classList.add('open');
console.log(`${skipTransitions()} Transition(en) übersprungen`);

2 Transition(en) übersprungen

Transition anhalten und an eine Stelle springen

const panel = document.querySelector('.panel');
panel.classList.add('expanded'); // löst z. B. eine height-Transition aus

const [transition] = panel
  .getAnimations()
  .filter((a) => a instanceof CSSTransition);

if (transition) {
  transition.pause();
  transition.currentTime = 250; // Millisekunden ab Beginn der Transition
  console.log(transition.playState, transition.currentTime);
}

paused 250

// Wichtig · Fallstricke

Kein Konstruktor: new CSSTransition() wirft einen TypeError. Instanzen erhält man nur über getAnimations().
Nur solange sie läuft: Nach dem Ende oder Abbruch taucht eine Transition nicht mehr in getAnimations() auf. Sie muss also abgefragt werden, solange sie aktiv ist oder in ihrer Verzögerung (transition-delay) wartet.
Keine Transition beim ersten Rendern: Bekommt ein frisch eingefügtes Element im selben Frame einen neuen Wert, entsteht keine Transition, weil noch kein Ausgangswert berechnet wurde.
Kurzschreibweisen: Bei transition: margin 1s entsteht für jede Einzeleigenschaft (margin-top, margin-left …) ein eigenes CSSTransition-Objekt. transitionProperty enthält immer den Longhand-Namen.
Abbruch statt Ende: Ändert sich der Zielwert während der Transition, wird die alte abgebrochen und eine neue gestartet. finished wird dann mit einem AbortError abgelehnt, deshalb sollte man den Fehler abfangen.
Überschreiben per Skript: Ruft man z. B. play() nach dem Ende auf oder setzt effect neu, hat spätere CSS-Stiländerungen unter Umständen keinen Einfluss mehr auf dieses Objekt.
Events: transitionrun, transitionstart, transitionend und transitioncancel werden am Element ausgelöst, nicht am CSSTransition-Objekt. Am Objekt selbst gibt es die Animation-Events finish und cancel.
Kompatibilität: Seit 2020 in allen modernen Browsern verfügbar. Für ältere Browser vorher prüfen: typeof CSSTransition !== 'undefined'.

Siehe auch

Animation CSSAnimation Element.prototype.getAnimations() Document.prototype.getAnimations() Animation.finished TransitionEvent