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.
document.addEventListener("DOMContentLoaded", () => { console.log("DOM ready"); }); window.addEventListener("load", () => { console.log("everything loaded"); });
Try it
Syntax
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 beforeDOMContentLoaded, 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
DOMContentLoadedlistener after the event has fired, it never runs. Checkdocument.readyStatefirst, as inwhenReady()above. - Scripts delay
DOMContentLoaded. A classic script withoutdeferorasyncblocks parsing, so the event waits for it. Deferred scripts run before the event;asyncscripts may run before or after it. loadwaits for resources. One slow image delaysload, which is why heavy initialization onloadmakes pages feel slow. Use it when you truly need sizes of images or all stylesheets applied.loadalso 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 settingsrcfor dynamically created elements.- Back/forward cache. When a page is restored from the browser's back/forward cache, neither event fires again. Use
pageshowand checkevent.persistedif you need to react. - Do not use
unload. It blocks the back/forward cache and is unreliable. Usepagehideorvisibilitychangeinstead. - Fonts. Web fonts may still be loading after
DOMContentLoaded. Usedocument.fonts.readyto wait for them.
Browser support
DOMContentLoaded, load, readystatechange and document.readyState work in every browser. pageshow and pagehide are supported in all current browsers.
Related
visibilitychangeโ the reliable event for leaving a pagebeforeunloadaddEventListener()โ including theonceoptionhashchangeandpopstate- Lessons: Events, Modules