Page & resource loading

The page has a timeline

Browser JavaScript is not only about what to run. A big part of professional front-end work is choosing when to run it. If code searches for a button before the browser has parsed that button, the search returns null. If code measures an image before the image loads, the size can be wrong. If code keeps polling while the tab is hidden, it wastes battery and network.

This lesson gives names to the important moments: the DOM becomes ready, resources finish, scripts join the queue, the page is hidden, and individual images either load or fail. We will use real sandboxed frames for startup timing so React does not manage the nodes we are poking, and a live page demo for visibility because that signal belongs to this actual tab.

If you want one rule to carry through the whole lesson, use this: choose the earliest event that has the facts you need. Earlier usually feels faster; later is only better when the job truly depends on later resources.

document.readyState moves through three values. It starts as loading while the parser is reading HTML. It becomes interactive when parsing is done, just before DOMContentLoaded. It becomes complete when the page’s load event is firing, after resources such as images and iframes are finished.

A common safe pattern is: if the document is still loading, add a DOMContentLoaded listener; otherwise run immediately. That second branch matters because adding a listener after the event already fired will not replay it for you.

1function onDomReady(callback) {2  if (document.readyState === "loading") {3    document.addEventListener("DOMContentLoaded", callback, { once: true });4  } else {5    callback();6  }7}8 9onDomReady(() => console.log("DOM is ready"));Run

Now watch a real document go through its startup events. The code runs inside a sandboxed srcdoc iframe with sandbox="allow-scripts". It posts messages out, and the lesson accepts only messages whose event.source is that exact frame.

1const started = performance.now();2const log = (label) => parent.postMessage({ type: "timeline", label, ms: Math.round(performance.now() - started), state: document.readyState }, "*");3log("script start");4document.addEventListener("readystatechange", () => log("readystatechange"));5document.addEventListener("DOMContentLoaded", () => log("DOMContentLoaded"));6window.addEventListener("load", () => log("window load"));7const img = document.querySelector("img");8img.addEventListener("load", () => log("image load"));9img.addEventListener("error", () => log("image error"));

In this server-free demo a data URL image can succeed and a deliberately broken data URL can fail. A generated data URL does not simulate a real slow network very well, so the experiment is honest about what it can prove: event order, readyState changes, and resource success/error.

Classic script tags affect parsing differently depending on their attributes. A normal external script is like a guest who stops the builders until they finish talking. A defer script waits politely until the house is built, then speaks in document order before DOMContentLoaded. An async script interrupts whenever it arrives, in whatever order downloads finish.

1log("parser before script");2<script src="data:text/javascript,..."></script>3log("parser after script");4document.addEventListener("DOMContentLoaded", () => log("DOMContentLoaded"));

Important details: defer and async apply to external classic scripts with src; they do not change inline classic scripts. Module scripts behave like defer by default, and can be made async. Also remember that a stylesheet can delay a script that comes after it, because the script might ask for computed styles.

A page does not always get a clean goodbye. Mobile browsers may freeze it. The user may put it into the back/forward cache and return without a full reload. That is why unload is a bad place for important work: it is unreliable and can block the back/forward cache.

Use visibilitychange when the page becomes hidden or visible. It is like someone leaving the room and turning off the TV: pause animations, stop polling, and send tiny final messages early. Use pagehide for page navigation signals, especially with event.persisted to notice bfcache. Use beforeunload only for the unsaved-changes prompt.

1document.addEventListener("visibilitychange", () => {2  if (document.visibilityState === "hidden") {3    pauseAnimation();4    navigator.sendBeacon?.("/analytics", draftSnapshot);5  } else {6    resumeAnimation();7  }8});9 10window.addEventListener("pagehide", (event) => {11  saveFast("leaving or entering bfcache", event.persisted);12});13 14function warnIfDirty(event) {15  event.preventDefault();16  event.returnValue = ""; // legacy signal; browsers ignore custom text17}18 19function setDirty(isDirty) {20  if (isDirty) {21    window.addEventListener("beforeunload", warnIfDirty);22  } else {23    window.removeEventListener("beforeunload", warnIfDirty);24  }25}

The beforeunload pattern is deliberately narrow: event.preventDefault() plus the legacy event.returnValue = "". Modern browsers show their own generic message, ignore custom text, and in most cases require the user to have interacted with the page first. Register it only while changes are actually unsaved, and remove it as soon as the page is clean.

1function warnIfDirty(event) {2  event.preventDefault();3  event.returnValue = ""; // legacy signal; browsers ignore custom text4}5 6function setDirty(isDirty) {7  if (isDirty) {8    window.addEventListener("beforeunload", warnIfDirty);9  } else {10    window.removeEventListener("beforeunload", warnIfDirty);11  }12}

The document has loading events, and so do many resource elements. Images, scripts, stylesheets, iframes, and other resources can fire load when they succeed and error when they fail. You can attach handlers with properties such as img.onload, but addEventListener is usually easier to compose and remove.

1function loadImage(src) {2  return new Promise((resolve, reject) => {3    const img = new Image();4    img.addEventListener("load", () => resolve(img));5    img.addEventListener("error", () => reject(new Error("Image failed")));6    img.src = src;7  });8}

Wrapping resource loading in a Promise is a practical form of promisification: translate callback-style events into a value you can await. If that idea is new, the Promisification lesson explains the general pattern.

1function loadImage(src) {2  return new Promise((resolve, reject) => {3    const img = new Image();4    img.addEventListener("load", () => resolve(img));5    img.addEventListener("error", () => reject(new Error("Image failed")));6    img.src = src;7  });8}

Lifecycle choices show up in ordinary product code: start menus as soon as the DOM exists, wait for a chart image before measuring, pause a dashboard when hidden, and save small data before the browser freezes the page. The sorter below asks for the earliest useful moment.

1function startWhenReady(setup) {2  if (document.readyState === "loading") {3    document.addEventListener("DOMContentLoaded", setup, { once: true });4  } else {5    setup();6  }7}8 9startWhenReady(() => {10  document.querySelector("#save").addEventListener("click", saveDraft);11});12 13document.addEventListener("visibilitychange", () => {14  if (document.visibilityState === "hidden") navigator.sendBeacon("/draft", currentDraft());15});

Common misconceptions

• “DOMContentLoaded means everything loaded.” It means the parsed DOM is ready and deferred/module scripts finished. Images and iframes can still be loading.
• “load is always better because it is safer.” It is later. Use it only when you need resources, not just elements.
• “async and defer work on inline scripts.” They matter for external classic scripts. Inline classic scripts run where they appear.
• “async scripts run after DOMContentLoaded.” They may run before or after it; the point is that download completion controls them.
• “beforeunload lets me write a custom warning.” Modern browsers show generic text, and the prompt is restricted.
• “unload is the right place for cleanup.” It is unreliable and harms bfcache. Prefer visibilitychange, pagehide, and sendBeacon for small work.

Key takeaways

• DOMContentLoaded is for parsed DOM; load is for resources too.
• Check document.readyState before adding a startup listener late.
• defer keeps external classic scripts ordered before DOMContentLoaded; async does not.
• Pause and save on visibilitychange/pagehide; avoid unload.
• Use resource load/error events for individual images and files.

Page lifecycle work means matching each piece of JavaScript to the earliest browser moment where the facts it needs are true.

Up next: Form properties & elements.