ViewTransition.skipTransition() — Methode · JavaScript-Referenz

Signatur

ViewTransition.prototype.skipTransition()

Beschreibung

skipTransition() bricht den animierten Teil einer View Transition ab. Die Aktualisierung der Ansicht selbst läuft trotzdem: Der an document.startViewTransition() übergebene Callback wird ausgeführt, auch wenn er noch nicht begonnen hat. Die Seite springt also sofort in den neuen Zustand, ohne Überblendung und ohne die Pseudo-Elemente ::view-transition-*.

Typische Einsatzfälle:

Nutzer bevorzugen reduzierte Bewegung (prefers-reduced-motion).
Eine neue Navigation oder Interaktion folgt so schnell, dass die laufende Animation nur stört.
Die Animation soll per Taste (z. B. Esc) oder über einen „Überspringen“-Button abgebrochen werden.
Unter bestimmten Bedingungen wirkt eine Animation unpassend, etwa bei sehr großen DOM-Änderungen.

Nach dem Aufruf wird das Promise ViewTransition.ready mit einem AbortError abgelehnt, sofern die Animation noch nicht bereit war. updateCallbackDone erfüllt sich, sobald der Callback fertig ist. finished erfüllt sich ebenfalls, allerdings erst, wenn das DOM-Update abgeschlossen ist. Code, der auf finished wartet, läuft also auch dann zuverlässig, wenn die Animation übersprungen wurde.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Den Zustand verfolgst du über die Promises ready, updateCallbackDone und finished des ViewTransition-Objekts.

Beispiele

Animation bei reduzierter Bewegung überspringen

const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)');

const updateView = (html) => {
  document.querySelector('#content').innerHTML = html;
};

const navigate = (html) => {
  // Fallback für Browser ohne View Transitions
  if (!document.startViewTransition) {
    updateView(html);
    return;
  }

  const transition = document.startViewTransition(() => updateView(html));

  if (reduceMotion.matches) {
    // Das DOM-Update läuft trotzdem, nur ohne Animation
    transition.skipTransition();
  }
};

navigate('<h1>Neue Seite</h1>');

Laufende Transition bei schneller Folgeinteraktion abbrechen

let currentTransition = null;

const showImage = (src) => {
  // Vorherige Animation sofort beenden
  currentTransition?.skipTransition();

  currentTransition = document.startViewTransition(() => {
    document.querySelector('#gallery img').src = src;
  });

  currentTransition.finished.finally(() => {
    currentTransition = null;
  });
};

document.querySelector('#next').addEventListener('click', () => {
  showImage(`/bilder/${Date.now() % 10}.jpg`);
});

Mit Escape überspringen und die Promises auswerten

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

  const onKey = (e) => {
    if (e.key === 'Escape') transition.skipTransition();
  };
  document.addEventListener('keydown', onKey);

  try {
    await transition.ready;
    console.log('Animation läuft');
  } catch (err) {
    console.log('Animation übersprungen:', err.name);
  }

  await transition.finished;
  document.removeEventListener('keydown', onKey);
  console.log('Theme gewechselt');
};

toggleTheme();

Animation übersprungen: AbortError Theme gewechselt

// Wichtig · Fallstricke

Ablehnung von ready: Wird die Animation übersprungen, bevor sie bereit war, wird transition.ready mit einem AbortError (DOMException) abgelehnt. Ohne catch erscheint in der Konsole eine Warnung über ein nicht behandeltes abgelehntes Promise („unhandled rejection“). Wenn du auf ready wartest, fange den Fehler also immer ab.
Callback läuft trotzdem: skipTransition() macht das DOM-Update nicht rückgängig und verhindert es auch nicht. Wenn du das Update verhindern willst, darfst du startViewTransition() gar nicht erst aufrufen.
Nach der Animation wirkungslos: Ist die Transition schon beendet, bewirkt ein Aufruf nichts und löst keinen Fehler aus.
Automatisches Überspringen: Der Browser bricht eine laufende Transition selbst ab, wenn eine neue mit startViewTransition() gestartet wird. Ein manueller Aufruf ist dafür nicht nötig, macht die Absicht im Code aber deutlicher.
Kompatibilität: Chromium ab Version 111, Safari ab 18, Firefox ab 144. Prüfe vorher mit if (document.startViewTransition), ob die API vorhanden ist. Bei seitenübergreifenden View Transitions (MPA) erreichst du das Objekt über event.viewTransition in den Events pageswap und pagereveal. Auch dort kannst du skipTransition() aufrufen.

Siehe auch

new TransitionEvent() ViewTransition.waitUntil() Selection.setPosition() Element.startViewTransition() Geolocation.watchPosition()