JavaScript Document prerenderingchange Event

What You’ll Learn

The Document prerenderingchange event fires when a prerendered page becomes active (the user views it). Learn MDN’s defer-analytics pattern, how it pairs with document.prerendering and activationStart, and five try-it labs.

Introduction

With the Speculation Rules API, browsers can load a page in the background before the user clicks. That hidden phase is prerendering. When the user finally navigates to that page, the prerender is activated—and prerenderingchange fires on the Document.

That moment is the safe point to start analytics, ads, client storage updates, or other work that should only run when someone is really viewing the page.

Understanding prerenderingchange

A Document event that answers: “Did this prerendered page just become the page the user is viewing?”

• Fires on a prerendered document when it is activated (MDN).
• Event type — a generic Event.
• Handler — document.onprerenderingchange or addEventListener("prerenderingchange", ...).
• Typical use — defer analytics and unsafe side effects until activation.
• Sibling property — document.prerendering is true during prerender.
• Status — Experimental and Limited availability on MDN (not Baseline).

📝 Syntax

Use the event name with addEventListener, or set the handler property on document:

addEventListener("prerenderingchange", (event) => { });

onprerenderingchange = (event) => { };

Event type

A generic Event.

MDN pattern — defer until activation

if (document.prerendering) {
  document.addEventListener("prerenderingchange", initAnalytics, {
    once: true,
  });
} else {
  initAnalytics();
}

Prerender status toolkit

⚠️ Why Delay Code Until Activation?

• Analytics — a background prerender is not a real page view yet.
• Ads / autoplay — start only when the user is looking.
• Server / storage writes — avoid updating carts or preferences during speculative load.
• Third-party scripts — many are not prerender-aware; load after activation.

See MDN’s Speculation Rules API and its unsafe speculative loading notes for more cases.

⚖️ prerenderingchange vs document.prerendering

Examples Gallery

Examples follow MDN Document: prerenderingchange event. On a normal lab load, document.prerendering is usually false, so the else branch runs—that is still the correct MDN pattern.

function initAnalytics() {
  console.log("Analytics initialized");
}

if (document.prerendering) {
  document.addEventListener("prerenderingchange", initAnalytics, {
    once: true,
  });
} else {
  initAnalytics();
}

Analytics initialized

const out = document.getElementById("out");

out.textContent =
  "prerendering now? " +
  ("prerendering" in document ? document.prerendering : "(unsupported)");

document.onprerenderingchange = () => {
  out.textContent = "prerenderingchange: page activated";
};

prerendering now? false

if (document.prerendering) {
  document.addEventListener(
    "prerenderingchange",
    () => {
      console.log("Prerender activated after this script ran");
    },
    { once: true },
  );
} else if (performance.getEntriesByType("navigation")[0]?.activationStart > 0) {
  console.log("Prerender activated before this script ran");
} else {
  console.log("This page load was not via prerendering");
}

This page load was not via prerendering

const out = document.getElementById("out");
const supported = "prerendering" in document;

if (!supported) {
  out.textContent = "prerendering API missing — run normal init";
  // initAnalytics();
} else if (document.prerendering) {
  document.addEventListener("prerenderingchange", () => {
    out.textContent = "Activated after prerender";
  }, { once: true });
  out.textContent = "Waiting for prerenderingchange...";
} else {
  out.textContent = "Supported; not prerendering — run normal init";
}

Supported; not prerendering — run normal init

function whenActivated(fn) {
  if ("prerendering" in document && document.prerendering) {
    document.addEventListener("prerenderingchange", fn, { once: true });
  } else {
    fn();
  }
}

whenActivated(() => {
  document.getElementById("out").textContent =
    "Safe to start analytics / ads now";
});

Safe to start analytics / ads now

🚀 Common Use Cases

• Deferring analytics until the user actually views a prerendered page.
• Loading third-party ad or chat scripts after activation.
• Updating carts / client storage only after a real navigation.
• Measuring how often Speculation Rules prerenders become visits.
• Teaching why pageshow alone is not enough for “user saw the page.”

🔧 How It Works

📝 Notes

• MDN: Experimental and Limited availability—Experimental banner shown above.
• Not Deprecated or Non-standard.
• On non-prerendered loads the event does not fire—always keep an else path.
• Do not use the defer-init pattern alone for activation metrics (MDN).
• Related learning: document.prerendering, hidden, DOMContentLoaded, JavaScript hub.

💡 Best Practices