DOMContentLoaded: what it is, vs load, and what delays it

What is DOMContentLoaded?

DOMContentLoaded is a browser event that fires when the HTML document has been completely parsed and the DOM tree is built, and all deferred scripts have run. It does not wait for images, stylesheets that are not blocking a script, iframes or other subresources to finish loading. That later point is the load event.

In performance tools you often see it as DCL, a marker on the network waterfall, or as "DOMContentLoaded time" in navigation timing.

DOMContentLoaded vs load vs user-centric metrics

DOMContentLoaded is a technical milestone for developers, not a measure of what users experience. A page can fire DCL early while the hero image is still loading, or late because a heavy script runs during parsing even though content was visible.

Reading it from navigation timing

Sample values for one page load, from performance.getEntriesByType("navigation")[0]:

The gap between domInteractive (820 ms, parsing done) and domContentLoadedEventStart (1,140 ms) is 320 ms spent running deferred scripts. The gap to domComplete (2,480 ms) is mostly images and other resources. Long DCL handler time (End − Start, 25 ms here) means code attached to the event is doing a lot of work.

What delays DOMContentLoaded

• Parser-blocking scripts. A plain <script src> in the head stops parsing until it downloads and runs.
• Stylesheets before scripts. A script after a stylesheet waits for that CSS, because the script might read styles.
• Deferred scripts. defer scripts run before DCL fires, so large deferred bundles push it back.
• Large HTML. Huge documents or deeply nested DOMs take longer to parse.
• Slow server response, which delays everything after it.

async scripts do not block parsing and may run before or after DCL; type="module" scripts are deferred by default.

Using the event in code

function init() {
  // safe to query and modify the DOM here
}

if (document.readyState === "loading") {
  document.addEventListener("DOMContentLoaded", init);
} else {
  init(); // DOM already parsed
}

Checking readyState first matters: if your script loads after the event has fired, a listener alone would never run. Analytics scripts commonly use this pattern to send the first pageview as soon as the DOM is ready.

How to improve it

1. Add defer or async to scripts that do not need to run during parsing.
2. Split and shrink JavaScript bundles; move non-critical work after load.
3. Inline the critical CSS and load the rest without blocking.
4. Reduce DOM size and avoid large inline scripts.
5. Speed up the server response and use a CDN.

In TapCub

TapCub's performance report measures real visits and splits each load into backend (time to first byte), network transfer and frontend render (from the end of the response until the document is complete), alongside Core Web Vitals at P75 and P95. It does not report DOMContentLoaded as a separate metric; frontend render covers the same parsing and script work plus subresources. The TapCub script itself waits for DOMContentLoaded only if the page is still loading, then records the pageview. See good page load time and Core Web Vitals.

Sources

• MDN Web Docs. Document: DOMContentLoaded event.
• WHATWG. HTML Living Standard: the end (parsing).
• Harry Roberts (2023). In defence of DOMContentLoaded.