Page & resource loading

The page has a timeline

A web page does not appear all at once. The browser reads the HTML from top to bottom and builds the page. Then it downloads images and other files. Your JavaScript must run at the right moment in that timeline.

Code that runs too early or too late causes real bugs:

• Code looks for a button before the browser has read that button. It gets null, which means "nothing found".
• Code measures an image before the image arrives. It gets the wrong size.
• Code keeps asking the server for news while the tab is hidden. It wastes battery and data.

This lesson names the important moments. Each moment is an event: a signal from the browser that your code can listen for. You will meet these moments:

• The HTML is fully read, and the DOM is ready. The DOM is the tree of elements the browser builds from your HTML.
• Every image and other file has finished loading.
• Scripts run, early or late, depending on how you add them.
• The page is hidden, or the user leaves it.
• One single image loads, or fails.

Some demos run a real page inside a small closed-off frame on this page, so you can watch it start up. The hidden-page demo uses this real tab, because "hidden" is about the tab you are reading.

One rule runs through the whole lesson: use the earliest event that already has what your code needs. An earlier event makes the page feel faster. Wait for a later event only when your code needs something that arrives later.

document.readyState is a word that says how far the page has got. It has three values, always in this order:

• loading: the browser is still reading the HTML.
• interactive: the HTML is fully read. DOMContentLoaded fires soon after, once any defer scripts have run. You will meet those in the next section.
• complete: images, iframes, and other files are done. The load event fires now.

Read each row of this table from left to right: the moment, what is ready, and whether it waits for images.

const states = ["loading", "interactive", "complete"];
console.log(states.join(" -> "));

Line 1 lists the three values in order. Line 2 joins them with arrows, so it prints loading -> interactive -> complete. These are steps the page goes through. You do not need to keep checking them in a loop.

const changes = ["interactive", "complete"];
for (const state of changes) {
  console.log("readystatechange: " + state);
}

readystatechange is an event that fires each time readyState changes. This loop copies that: it prints one line for each change. So a readystatechange listener can run more than once. If you want one clear starting point, listen for the event made for it, such as DOMContentLoaded.

A safe startup helper has two branches:

• If readyState is still loading, add a DOMContentLoaded listener.
• Otherwise, run the code right away.

The second branch matters. If you add a listener after DOMContentLoaded has already fired, the browser does not fire it again. Your listener would never run.

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 page start up. Its code runs inside an iframe: a small page shown inside this page. Three things keep it safe and separate:

• Its HTML comes from the srcdoc attribute, not from a server.
• sandbox="allow-scripts" lets it run scripts but cuts it off from this page.
• It sends each event out with postMessage. This page accepts a message only when 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"));

The images here are data URLs: the image data is written inside the address itself, so no server is needed. One image is good, and one is broken on purpose. A data URL arrives almost at once, so this demo cannot copy a slow network. It does show three real things:

• the order of the events,
• how readyState changes,
• whether the image loaded or failed.

A script tag can change how the browser reads the page. It depends on the tag's attributes, the extra words inside the tag such as defer. These rules are about external scripts: scripts loaded from a file with src.

• A normal external script stops the browser from reading the HTML. The browser downloads the script, runs it, and only then reads on.
• A defer script downloads while the browser keeps reading. It runs after all the HTML is read, in page order, before DOMContentLoaded.
• An async script also downloads while the browser keeps reading. It runs as soon as it arrives, in whatever order the downloads finish.

function chooseScriptMode(needsOrder) {
  return needsOrder ? "defer" : "async";
}

console.log(chooseScriptMode(true));
console.log(chooseScriptMode(false));

The first call says the script needs order, so it prints defer. The second call says the script works on its own, so it prints async. Choose by what the script needs, not by which word sounds faster.

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

A few more details to remember:

• defer and async only change external classic scripts. A classic script is a normal script, not a module. An inline script, written straight inside the tag, runs right where it appears.
• Module scripts (type="module") wait like defer by default. You can add async to them too.
• A stylesheet can delay a script that comes after it. The script might ask for the page's styles, so the browser waits for the stylesheet first.

A page does not always get a clean goodbye:

• A phone browser may freeze a page that is in the background.
• When the user presses Back, the browser may bring the page back from the back/forward cache, or bfcache. This cache keeps a whole page in memory, so Back is instant and nothing reloads.

So unload, the event for a page closing, is a bad place for important work. It often does not fire. Using it can also stop the bfcache from working.

visibilitychange says the page was hidden or shown. It does not promise that the page is closing. A hidden page may come back, freeze, or be thrown away. So save a small copy that is safe to save more than once. Do not count on one last callback.

Use each event for its own job:

• visibilitychange: the page became hidden or visible. Pause animations, stop asking the server for updates, and send small final messages early.
• pagehide: the user is leaving the page. Its event.persisted is true when the page is going into the bfcache.
• beforeunload: only for the "you have unsaved changes" warning.

function workFor(state) {
  return state === "hidden" ? "pause and save" : "resume";
}

console.log(workFor("hidden"));
console.log(workFor("visible"));

The first call prints pause and save because the page is hidden. The second prints resume because the page is visible again. In a real listener, document.visibilityState gives you the state: "hidden" or "visible".

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}

Keep the beforeunload code small. It needs two lines:

• event.preventDefault() asks the browser to show its warning.
• event.returnValue = "" asks the same thing in older browsers.

Modern browsers show their own general message and ignore any text you write. Most also show it only if the user has clicked or typed on the page. Add the listener only while there are unsaved changes. Remove it as soon as the work is saved.

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}

Lines 2 and 3 ask for the warning. Line 8 adds the listener when there are unsaved changes. Line 10 removes it when there are none.

navigator.sendBeacon(url, data) sends a small piece of data to the server, even while the page is going away. It returns true if the browser accepted the data for sending, or false if not. Use it for small messages such as analytics, which are counts of what users do. Do not wait for a reply, and do not send a large draft with it.

function queueAnalytics(bytes) {
  return bytes <= 64 * 1024 ? "queued" : "too large";
}

console.log(queueAnalytics(120));
console.log(queueAnalytics(70000));

This model prints queued for a small amount of data and too large for a big one. The 64 KB limit here is only for the model. The real limit is up to the browser, so check the true or false result. Do not assume the data was sent.

function describeReturn(persisted) {
  return persisted ? "restore cached page" : "start a fresh page";
}

console.log(describeReturn(true));
console.log(describeReturn(false));

pageshow fires when a page is shown, including after Back. Its event.persisted is true when the page came from the bfcache. This model copies that: true prints restore cached page, and false, a normal load, prints start a fresh page.

The whole page has load events. So does each single file. Images, scripts, stylesheets, and iframes each fire their own events:

• load when the file arrives and works.
• error when it fails.

You can set a handler with a property, such as img.onload. addEventListener is usually better: you can add more than one listener and remove them later.

function imageMessage(eventName) {
  return eventName === "load" ? "show image" : "show fallback";
}

console.log(imageMessage("error"));
console.log(imageMessage("load"));

The first call prints show fallback because the image failed. A fallback is something to show instead, such as a plain placeholder box. The second call prints show image.

In real code, add both listeners before you set src. Otherwise a fast image could finish before your listeners exist.

const events = ["load", "error"];
for (const event of events) {
  console.log(event + " means a resource outcome");
}

This loop prints one line for each event. A file that works fires load. A file that fails, or cannot be read, fires error.

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}

You can wrap these events in a Promise: an object for a result that comes later, which you can await. Turning event code into a Promise is called promisification. If that idea is new, the Promisification lesson explains it.

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}

• Line 3 makes a new image.
• Line 4 resolves the Promise with the image when load fires.
• Line 5 rejects the Promise with an error when error fires.
• Line 6 sets src last, so loading starts only after both listeners exist.

An error event says the file failed, but not why. Show a useful fallback. Do not guess the cause, and do not show the full address of a file that comes from another site.

These choices show up in everyday code:

• Start a menu as soon as its elements exist.
• Wait for a chart image before you measure it.
• Pause a dashboard while its tab is hidden.
• Save a small piece of data before the browser freezes the page.

function momentFor(job) {
  if (job === "wire buttons") return "DOMContentLoaded";
  if (job === "pause dashboard") return "visibilitychange";
  return "resource load";
}

console.log(momentFor("wire buttons"));
console.log(momentFor("pause dashboard"));
console.log(momentFor("wait for chart image"));

Wiring buttons prints DOMContentLoaded. Pausing a dashboard prints visibilitychange. Any other job, such as waiting for a chart image, reaches line 4 and prints resource load.

The sorter below asks for the moment that fits each task best.

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});

• Line 2 checks whether the HTML is still being read.
• Line 9 passes in the setup code, which adds a click listener to the Save button.
• Line 13 listens for the page being hidden or shown. When it is hidden, line 14 sends the draft with sendBeacon.

Common misconceptions

• “DOMContentLoaded means everything has loaded.” It means every element exists, and defer and module scripts have finished. Images and iframes may still be loading.
• “load is always better because it is safer.” It is only later. Use load when you need images or other files, not just elements.
• “async and defer work on inline scripts.” They only change external classic scripts, the ones with src. An inline classic script runs right where it appears.
• “async scripts run after DOMContentLoaded.” They may run before it or after it. Each one runs when its download finishes.
• “beforeunload lets me write my own warning.” Modern browsers show their own general text, and only in some cases.
• “unload is the right place for cleanup.” It often does not fire, and it can stop the bfcache from working. Use visibilitychange, pagehide, and sendBeacon for small final work.

Each row of this table is one event: what to use it for, and what not to use it for.

Key takeaways

• DOMContentLoaded fires when every element exists. load also waits for images and other files.
• Check document.readyState before you add a startup listener, in case the event has already fired.
• defer runs external classic scripts in page order, before DOMContentLoaded. async does not keep the order.
• Pause and save on visibilitychange or pagehide. Avoid unload.
• Use an image's own load and error events to handle that one file.

Page lifecycle work means running each piece of JavaScript at the earliest moment when everything it needs is ready.

Up next: Form properties & elements.