JavaScript Document DOMContentLoaded Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word DOMCONTENTLOADED

Definition

In JavaScript, the Document DOMContentLoaded event fires when the HTML has been completely parsed and deferred scripts (defer / type="module") have downloaded and executed (MDN). It does not wait for images, subframes, or async scripts.

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for DOMContentLoaded. Start with this line.

JavaScript
document.addEventListener("DOMContentLoaded", fn)
CallWhat it does
document.addEventListener("DOMContentLoaded", fn)Primary signature.

Built into the browser. Listen with document.addEventListener("DOMContentLoaded", …) — no import required.

Library declarations
JavaScript
document.addEventListener("DOMContentLoaded", fn)

Parameters

ParameterDescription
addEventListenerRequired. Only supported registration style (MDN)
readyState guardOptional. Handles scripts that miss the event

Return Value

Return ValueDescription
*Fires as a Document event (listener receives the Event object).

JavaScript Examples

Example 1 — Basic DOMContentLoaded Listener

MDN style: wait until the HTML is parsed, then query the DOM.

JavaScript
document.addEventListener("DOMContentLoaded", (event) => {
  console.log("DOM fully loaded and parsed");
  const title = document.querySelector("h1");
  console.log("Found h1:", title ? title.textContent : "(none)");
});
Try It Yourself

How It Works

  1. Register the listener. Use addEventListener — there is no onDOMContentLoaded.
  2. Wait for parse. The handler runs after the HTML (and deferred scripts) are ready.
  3. Query the DOM. querySelector("h1") is safe inside the handler.
  4. No images wait. Pictures and other sub-resources may still be loading.

Example 2 — readyState Guard

MDN pattern for scripts that might run after the event already fired.

JavaScript
function doSomething() {
  console.info("DOM loaded");
}

if (document.readyState === "loading") {
  document.addEventListener("DOMContentLoaded", doSomething);
} else {
  doSomething();
}

console.log("readyState now:", document.readyState);
Try It Yourself

How It Works

  1. Define setup once. doSomething is the shared DOM-ready work.
  2. Still loading? Attach a DOMContentLoaded listener.
  3. Already past? Call doSomething() immediately.
  4. No race. MDN: JavaScript run-to-completion means the document cannot flip between the check and addEventListener.

Example 3 — DOMContentLoaded vs load

Use the right event: DOM ready vs full page ready (MDN).

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

window.addEventListener("load", () => {
  console.log("load — full page (images, etc.)");
});

console.log("Listeners attached");
console.log("Prefer DOMContentLoaded when you only need the DOM");
Try It Yourself

How It Works

  1. Listen on Document. DOMContentLoaded means the HTML tree is ready.
  2. Listen on Window. load waits for images and other sub-resources too.
  3. Usual order. DOMContentLoaded fires first; load fires later.
  4. Pick intentionally. MDN: it is a common mistake to use load when DOMContentLoaded is enough.
Compatibility

Browser Support

Document DOMContentLoaded is Baseline Widely available (MDN, since July 2015). It is a standard Document event — not Deprecated, Experimental, or Non-standard.

✓ Baseline · Widely available

Document DOMContentLoaded

Fires when the HTML is fully parsed (before images). Use addEventListener — no onDOMContentLoaded property.

99% Modern browser support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
DOMContentLoaded Excellent

Bottom line: Safe for virtually all browsers students use today. Prefer it over window load when you only need the DOM, and guard late scripts with document.readyState.

Frequently Asked Questions

It fires on Document when the HTML has been completely parsed and deferred scripts (defer and type="module") have downloaded and executed. It does not wait for images, subframes, or async scripts (MDN).
No. MDN marks it Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
No. MDN notes there is no onDOMContentLoaded event handler property. Use document.addEventListener("DOMContentLoaded", handler).
DOMContentLoaded means the DOM is ready. The window load event waits for the full page including images and other sub-resources. Prefer DOMContentLoaded when you only need the DOM (MDN).
Check document.readyState. If it is still "loading", add a DOMContentLoaded listener; otherwise run your setup immediately. This matters for async scripts, dynamic imports, and injected scripts (MDN).
No. It is a generic Event and is not cancelable (MDN).

Next: fullscreenchange

Learn the Document event that fires when fullscreen mode changes.

fullscreenchange tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document beforescriptexecute Event JavaScript Document fullscreenchange Event