Window: pagereveal — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("pagereveal", handler)

Beschreibung

Das Ereignis pagereveal tritt auf Window auf, sobald ein Dokument zum ersten Mal sichtbar gerendert werden soll. Das gilt für drei Fälle: Das Dokument wird frisch aus dem Netzwerk geladen, es wird aus dem Back-/Forward-Cache (bfcache) wiederhergestellt, oder ein vorgerendertes Dokument (Prerendering über die Speculation Rules API) wird aktiviert. Das Ereignis wird bei der ersten Rendering-Gelegenheit ausgelöst, also bevor der erste Frame gezeichnet wird.

Das Ereignisobjekt ist ein PageRevealEvent. Seine wichtigste Eigenschaft ist viewTransition: Läuft gerade eine dokumentübergreifende View Transition (aktiviert per CSS @view-transition { navigation: auto; }), steht dort das zugehörige ViewTransition-Objekt, sonst null.

Wofür braucht man das? pagereveal ist das Gegenstück zu pageswap auf der alten Seite. Auf der neuen Seite kannst du damit den eingehenden Übergang anpassen: Übergangstypen setzen (viewTransition.types), view-transition-name gezielt an einzelne Elemente vergeben oder den Übergang mit skipTransition() abbrechen. Informationen über die Herkunft der Navigation liefert navigation.activation aus der Navigation API.

Du kannst den Handler per addEventListener("pagereveal", …) registrieren oder über die Eigenschaft window.onpagereveal. Wichtig ist, dass du ihn früh registrierst, am besten in einem klassischen, blockierenden <script> im <head>. Sonst ist das Ereignis beim ersten Frame womöglich schon vorbei.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"pagereveal"`.
$handler Pflicht	(event: PageRevealEvent) => void		Callback, der ein `PageRevealEvent` erhält. Wichtige Eigenschaft: `event.viewTransition` (`ViewTransition \| null`).
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen von `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Beispiele

Richtung des Übergangs anhand der Herkunft festlegen

// Im <head> als klassisches Skript einbinden (nicht async/defer/module)
// CSS: @view-transition { navigation: auto; }
window.addEventListener("pagereveal", async (event) => {
  if (!event.viewTransition) return; // keine View Transition aktiv

  const activation = window.navigation?.activation;
  if (!activation?.from) return;

  const fromPath = new URL(activation.from.url).pathname;
  const toPath = new URL(activation.entry.url).pathname;

  // Übergangstyp setzen, auf den CSS per :active-view-transition-type() reagiert
  const isBack = activation.navigationType === "traverse" || toPath === "/";
  event.viewTransition.types.add(isBack ? "backwards" : "forwards");

  await event.viewTransition.finished;
  console.log(`Übergang ${fromPath} → ${toPath} fertig`);
});

Übergang /produkte → /produkte/42 fertig

Gezielt einen view-transition-name vergeben und danach aufräumen

window.addEventListener("pagereveal", async (event) => {
  if (!event.viewTransition) return;

  const hero = document.querySelector(".produkt-bild");
  if (!hero) return;

  // Nur während des Übergangs benennen, damit Namen eindeutig bleiben
  hero.style.viewTransitionName = "hero";
  await event.viewTransition.ready;
  hero.style.viewTransitionName = "";
});

Übergang bei reduzierter Bewegung überspringen (on-Property)

window.onpagereveal = (event) => {
  const reduce = matchMedia("(prefers-reduced-motion: reduce)").matches;
  if (event.viewTransition && reduce) {
    event.viewTransition.skipTransition();
    console.log("View Transition übersprungen");
  }
};

View Transition übersprungen

Einmaliges Logging und Entfernen des Listeners

const onReveal = (event) => {
  console.log("Seite sichtbar, Transition:", event.viewTransition !== null);
  window.removeEventListener("pagereveal", onReveal);
};

window.addEventListener("pagereveal", onReveal);
// Alternativ kürzer: addEventListener("pagereveal", fn, { once: true })

Seite sichtbar, Transition: false

// Wichtig · Fallstricke

Früh registrieren: Das Ereignis fällt vor den ersten Frame. Skripte mit async, defer oder type="module" laufen dafür unter Umständen zu spät. Nutze ein klassisches Skript im <head>. Wenn der Handler auf bestimmte DOM-Elemente zugreift, kannst du das Rendering zusätzlich mit <link rel="expect" href="#id" blocking="render"> blockieren, bis diese Elemente geparst sind.
event.viewTransition ist null, wenn keine View Transition läuft. Das ist etwa beim ersten Aufruf, bei ursprungsübergreifenden Navigationen, ohne @view-transition { navigation: auto; } oder bei Zeitüberschreitung der Fall. Prüfe den Wert deshalb immer.
Das Ereignis wird auch bei Wiederherstellung aus dem bfcache und bei Aktivierung vorgerenderter Seiten ausgelöst. Es kann also mehrfach pro Dokument auftreten. Bei bfcache-Wiederherstellung kommt es nach pageshow.
navigation.activation (Navigation API) wird nicht in allen Browsern unterstützt. Greife defensiv darauf zu, z. B. mit window.navigation?.activation. Auch activation.from kann null sein.
Browserunterstützung: Chromium ab Version 123, Safari ab 18.2. In Firefox fehlt die Unterstützung noch bzw. ist erst im Aufbau. Nutze das Ereignis daher nur als progressive Verbesserung.
view-transition-name-Werte müssen im Dokument eindeutig sein. Doppelte Namen lassen den Übergang abbrechen.

Siehe auch

Window: pageswap Window: pageshow Navigation.activation Element: pointermove Window: pagehide