CKTIS / JavaScript
DOMContentLoaded and pagehide events
Use `DOMContentLoaded` to initialize code once the DOM is built, and `pagehide` to pause work when leaving a document. A bfcache restore is not a fresh load.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
document.addEventListener("DOMContentLoaded", onReady, { once: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);DOMContentLoaded is an Event dispatched on document after HTML parsing, after the browser has run deferred classic scripts and initiated evaluation of the non-async module scripts scheduled for the end of parsing. It does not wait for module evaluation to finish: if a dependency suspends at a top-level await, the event can fire before the importing module's body even starts running. It does not wait for images, frames, or async scripts to finish. Stylesheets can delay it indirectly by blocking script execution. Use load on window when you need to wait for resources that delay page loading.
If initialization code can start late, check document.readyState: while it is "loading", register a one-time DOMContentLoaded listener; otherwise, use the DOM that is already available. "interactive" means parsing has finished, not that the event has necessarily fired or that other scripts have finished their setup. If you depend on another script's setup, arrange the initialization order explicitly.
Listen for pagehide on window when leaving a document, for example during Back navigation. It is a PageTransitionEvent, not a notification that the user merely switched tabs, and it cannot cancel navigation. event.persisted === true means the document may be kept in the back/forward cache (bfcache), not that it is guaranteed to be restored. false means the document is not being kept for that navigation. Pause work on pagehide and resume it on pageshow with persisted === true: a restored document retains its DOM and does not fire DOMContentLoaded again.
Save important data as you go: pagehide can be missed, especially if a mobile browser is forcibly closed, and asynchronous work started there may not finish. To respond to the page becoming hidden, listen for visibilitychange on document and check for "hidden". These are web platform APIs, not features added in ECMAScript 2024.
Examples
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DOMContentLoaded and pagehide</title>
<script>
(() => {
const init = () => console.log("DOM ready");
if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", init, { once: true });
} else {
init();
}
window.addEventListener("pagehide", (event) => {
console.log(`pagehide persisted=${event.persisted}`);
});
window.addEventListener("pageshow", (event) => {
if (event.persisted) console.log("pageshow restored");
});
})();
</script>
</head>
<body>
<p>Open the browser console to see the event log.</p>
</body>
</html>Result
DOM ready
Save the example as an HTML file and open it in a browser. Enable Preserve log in the console and reload. `DOM ready` appears when `DOMContentLoaded` fires. Later messages depend on navigation and whether the browser keeps the document.
Related lessons
- JavaScript · Lesson 40 · Advanced · Version: 4
- JavaScript · Lesson 41 · Advanced · Version: 4