ViewTransition.ready — Eigenschaft · JavaScript-Referenz

Signatur

ViewTransition.ready

Beschreibung

Die Eigenschaft ready eines ViewTransition-Objekts liefert ein Promise<undefined>. Es wird erfüllt, sobald der Browser die Momentaufnahme des alten Zustands erstellt, den DOM-Update-Callback ausgeführt und den Baum der Pseudo-Elemente (::view-transition, ::view-transition-group(), ::view-transition-old(), ::view-transition-new()) aufgebaut hat – also direkt bevor die Übergangsanimation beginnt.

Wichtigster Einsatzzweck: eigene Animationen per JavaScript auf den Pseudo-Elementen starten, etwa mit document.documentElement.animate() und der Option pseudoElement. Das geht erst, wenn die Pseudo-Elemente existieren – genau das signalisiert ready. Typisches Beispiel ist ein kreisförmiger Aufdeck-Effekt, der von der Klickposition ausgeht und dessen Radius zur Laufzeit berechnet wird.

Das Promise wird abgelehnt, wenn der Übergang nicht starten kann: Der Update-Callback wirft einen Fehler bzw. liefert ein abgelehntes Promise, zwei Elemente haben denselben view-transition-name, der Übergang wurde mit skipTransition() übersprungen, bevor er bereit war, oder das Dokument wurde versteckt. Ein abgelehntes ready bedeutet nicht zwingend, dass das DOM-Update gescheitert ist – dafür gibt es updateCallbackDone.

Zeitliche Reihenfolge der drei Promises: updateCallbackDone → ready → finished.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Promise, das mit undefined erfüllt wird, sobald die Pseudo-Elemente erstellt sind und die Animation gleich startet. Wird abgelehnt, wenn der Übergang nicht starten kann (z. B. InvalidStateError bei doppeltem view-transition-name oder AbortError beim Überspringen).

Beispiele

Kreisförmiger Aufdeck-Effekt ab der Klickposition

const toggleTheme = async (event) => {
  const toggle = () => document.documentElement.classList.toggle('dark');

  // Fallback ohne View-Transitions-Unterstützung
  if (!document.startViewTransition) {
    toggle();
    return;
  }

  const x = event.clientX;
  const y = event.clientY;
  const endRadius = Math.hypot(
    Math.max(x, innerWidth - x),
    Math.max(y, innerHeight - y)
  );

  const transition = document.startViewTransition(toggle);

  // Erst jetzt existieren die Pseudo-Elemente
  await transition.ready;

  document.documentElement.animate(
    {
      clipPath: [
        `circle(0px at ${x}px ${y}px)`,
        `circle(${endRadius}px at ${x}px ${y}px)`
      ]
    },
    {
      duration: 500,
      easing: 'ease-in-out',
      pseudoElement: '::view-transition-new(root)'
    }
  );
};

document.querySelector('#theme-button').addEventListener('click', toggleTheme);

Fehler beim Start abfangen

const transition = document.startViewTransition(() => {
  document.querySelector('#liste').innerHTML = '<li>Neu</li>';
});

try {
  await transition.ready;
  console.log('Animation startet jetzt');
} catch (err) {
  // z. B. doppelter view-transition-name oder übersprungen
  console.warn('Übergang nicht gestartet:', err.name);
}

await transition.finished;
console.log('Übergang abgeschlossen');

Animation startet jetzt Übergang abgeschlossen

Reihenfolge der drei Promises beobachten

const transition = document.startViewTransition(async () => {
  document.body.classList.toggle('detailansicht');
});

transition.updateCallbackDone.then(() => console.log('1. DOM aktualisiert'));
transition.ready.then(() => console.log('2. Pseudo-Elemente bereit'));
transition.finished.then(() => console.log('3. Animation beendet'));

1. DOM aktualisiert 2. Pseudo-Elemente bereit 3. Animation beendet

// Wichtig · Fallstricke

Unbehandelte Ablehnungen: Wenn der Übergang übersprungen wird, lehnt ready ab. Ohne catch erscheint in der Konsole ein Unhandled Promise Rejection. Wer ready nicht braucht, sollte es auch nicht anfassen; wer es nutzt, sollte Fehler abfangen.
Nicht für DOM-Arbeit verwenden: Wenn ready erfüllt wird, ist das DOM bereits aktualisiert. Um zu wissen, ob das Update geklappt hat, updateCallbackDone nutzen, und für Aufräumarbeiten nach der Animation finished.
Animationen auf Pseudo-Elementen werden am Wurzelelement gestartet: document.documentElement.animate(keyframes, { pseudoElement: '::view-transition-new(root)' }). Eine gleichzeitige CSS-Animation sollte man ggf. mit animation: none abschalten, sonst überlagern sich beide.
Barrierefreiheit: prefers-reduced-motion berücksichtigen und die Animation in diesem Fall weglassen oder abschwächen.
Kompatibilität: Same-document View Transitions gibt es in Chromium ab 111, Safari ab 18 und Firefox ab 144. Vorher per if (document.startViewTransition) prüfen. Bei dokumentübergreifenden Übergängen (MPA) bekommt man das ViewTransition-Objekt über die Events pageswap/pagereveal.

Siehe auch

Element.animate() CSSViewTransitionRule.types ViewTransition.types ViewTransition.finished ViewTransition.transitionRoot