Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Events

The DOMContentLoaded and load events

Reference for DOMContentLoaded, load, readystatechange and document.readyState: when each fires, how scripts affect them and how to run code at the right time.

A page loads in stages, and the browser reports them with events. DOMContentLoaded fires when the HTML has been fully parsed and the DOM tree is built, and all deferred and module scripts have run. It does not wait for images, subframes or other resources. load fires on window later, when the page and its dependent resources (images, stylesheets, frames) have finished loading.

For most DOM code, DOMContentLoaded is the right moment: elements exist and you do not have to wait for large images. A property called document.readyState tells you which stage you are in, so you can also check it directly.

JavaScript
document.addEventListener("DOMContentLoaded", () => {
  console.log("DOM ready");
});

window.addEventListener("load", () => {
  console.log("everything loaded");
});

Try it

The order of lifecycle events
A helper that works at any time

Syntax

JavaScript
document.addEventListener("DOMContentLoaded", listener);
window.addEventListener("load", listener);
document.addEventListener("readystatechange", listener);
console.log(document.readyState);

document.readyState

Value Meaning
"loading" The document is still being parsed.
"interactive" Parsing has finished; DOMContentLoaded is about to fire or has just fired.
"complete" The page and its resources have loaded; load is about to fire.

The readystatechange event fires on document each time the value changes. DOMContentLoaded fires on document and bubbles up to window; load fires on window. Neither is cancelable.

Usage notes

  • You often do not need DOMContentLoaded. A <script defer> or <script type="module"> runs after the DOM is parsed and before DOMContentLoaded, in document order. A classic script at the end of <body> also sees all elements above it.
  • Registering too late is a silent bug. If you add a DOMContentLoaded listener after the event has fired, it never runs. Check document.readyState first, as in whenReady() above.
  • Scripts delay DOMContentLoaded. A classic script without defer or async blocks parsing, so the event waits for it. Deferred scripts run before the event; async scripts may run before or after it.
  • load waits for resources. One slow image delays load, which is why heavy initialization on load makes pages feel slow. Use it when you truly need sizes of images or all stylesheets applied.
  • load also fires on elements that load something: <img>, <script>, <link>, <iframe>. These do not bubble, so listen on the element itself, and add the listener before setting src for dynamically created elements.
  • Back/forward cache. When a page is restored from the browser's back/forward cache, neither event fires again. Use pageshow and check event.persisted if you need to react.
  • Do not use unload. It blocks the back/forward cache and is unreliable. Use pagehide or visibilitychange instead.
  • Fonts. Web fonts may still be loading after DOMContentLoaded. Use document.fonts.ready to wait for them.

Browser support

DOMContentLoaded, load, readystatechange and document.readyState work in every browser. pageshow and pagehide are supported in all current browsers.