Last month I reviewed a production bug where a checkout button stopped working on first paint. The handler was wired before the DOM existed, so it silently failed. A week later, another team measured hero image size on DOMContentLoaded and got zero, which cascaded into layout math that shifted the page. These two problems share the same root: a misunderstanding of when the browser considers the page ready.
Two events mark key milestones: DOMContentLoaded and load. The first fires when the HTML has been parsed and the DOM tree is ready. The second fires later, after images, stylesheets, fonts, and other subresources have finished loading. Picking the right one affects interactivity, layout accuracy, and perceived speed. I’ll walk through how each event fits in the page lifecycle, where I use them in real projects, and how I avoid timing bugs in modern apps.
Why timing matters in the browser
Browsers are fast, but they are also strict about ordering. HTML is parsed into a DOM tree while the network fetches CSS, scripts, images, and fonts. When the parser hits a blocking script tag, it pauses, runs that script, and then continues. Stylesheets can also block because a script that reads styles needs a ready CSSOM. That means the moment a node exists in markup is not always the moment it is safe to touch in JavaScript.
On the main thread, parsing, script execution, layout, and paint all compete. If you attach listeners too early, selectors return null or bind to the wrong elements. If you wait too long, your UI looks idle even though the markup is visible. In my experience, this is one of the top sources of subtle production bugs, especially when several teams contribute scripts to the same page.
Another reason this matters is perceived speed. Users start interacting as soon as they see buttons, even if images are still downloading. If your app waits for load to wire events, you can create dead clicks that feel broken. On the other hand, if you calculate layout before fonts or images arrive, the page can jump and reflow. That jump can raise CLS scores and make the UI feel unstable.
Modern apps in 2026 add more nuance. Streaming HTML from edge renderers means the DOM is built progressively. Partial hydration and island architectures allow chunks of the page to become interactive at different times. The event you choose becomes a policy decision: do you want the earliest moment the DOM exists, or the latest moment when everything on screen is stable? For interactive controls, I aim for the earliest safe moment. For layout measurements or visual snapshots, I wait for assets. Knowing the difference between DOMContentLoaded and load turns that decision from guesswork into a reliable rule you can apply across projects.
Event timeline from parse to pixels
To make the difference concrete, I map the page lifecycle to a simple timeline. Actual numbers vary by device and network, but ranges help frame expectations.
- 0–50ms: navigation starts, DNS/TCP/TLS, initial request
- 50–200ms: first bytes of HTML arrive, parser begins building the DOM
- 200–800ms: CSS and JS discovered; CSSOM builds; blocking scripts run
- 500–1500ms:
DOMContentLoadedfires once the DOM is complete and blocking scripts are done - 800–3000ms+: subresources finish (images, fonts, iframes, async chunks)
- 1200–4000ms+:
loadfires after all subresources are done
Two key nuances often get missed:
1) DOMContentLoaded waits for blocking scripts to execute, but not for images, fonts, or iframes. If a blocking script is slow, DOMContentLoaded is delayed.
2) load waits for every subresource, including those you didn’t realize were on the page (tracking pixels, chat widgets, embedded videos). One slow CDN or third-party can delay it by seconds.
When I’m debugging timing issues, I look at this as a pipeline. The DOM is the “structure done” milestone, and load is the “everything done” milestone. I never rely on one as a proxy for the other.
A precise definition of each event
If I had to describe each event in a single sentence:
DOMContentLoaded: the browser finished parsing HTML, built the DOM, and executed blocking scripts.load: the browser finished loading every dependent subresource referenced by the document.
Here’s a more detailed breakdown of what each one guarantees and what it does not:
What DOMContentLoaded guarantees
- You can query and traverse the DOM reliably.
- Inline scripts and blocking external scripts have executed.
- The document’s structure exists and is stable unless future scripts mutate it.
What DOMContentLoaded does not guarantee
- Images, fonts, videos, and iframes are loaded.
- Computed layout sizes are final (images or fonts might change measurements).
- CSS from non-blocking sources (like preloaded or deferred styles) is applied.
What load guarantees
- All images, fonts, stylesheets, scripts, and iframes referenced by the document are done.
- The DOM has already been ready for a while (so it is safe for DOM work).
- Layout sizes are more likely to be final, though runtime mutations can still occur.
What load does not guarantee
- That user interaction hasn’t already started (users can click long before
load). - That your app’s async data fetching is finished (the event is about subresources, not API calls).
- That your SPA route is fully hydrated if you render after
load.
The canonical difference in one table
I use a small table like this in onboarding docs to align teams on expectations:
DOMContentLoaded
load —
DOM is parsed, blocking scripts done
No
Yes
Sometimes, but risky
Indirectly (if blocking)
Early interactivity
Why DOMContentLoaded is usually the right default
If I’m wiring UI interactions—buttons, menus, toggles, input validation—I usually prefer DOMContentLoaded. It’s the earliest time that reliably guarantees the elements exist. Waiting for load means that users can click a visible button and nothing happens, which feels broken.
A typical pattern looks like this:
document.addEventListener(‘DOMContentLoaded‘, () => {
const button = document.querySelector(‘#checkout‘);
if (!button) return;
button.addEventListener(‘click‘, handleCheckout);
});
In production, I often add defensive guards too, especially on shared templates:
document.addEventListener(‘DOMContentLoaded‘, () => {
const button = document.querySelector(‘#checkout‘);
if (!button) {
console.warn(‘Checkout button not found‘);
return;
}
button.addEventListener(‘click‘, handleCheckout);
});
The guard isn’t just to avoid errors; it helps detect mismatches between markup and JS, which is common when multiple teams touch the same page.
When load is the safer choice
load shines when you need asset-dependent measurements or when you want to capture a stable visual state. A few common cases:
- Measuring hero image dimensions before calculating layout.
- Rendering a canvas snapshot that depends on background images.
- Initializing a masonry layout where image heights matter.
- Running visual regression tests that need the final render.
A classic example is a gallery layout that depends on image sizes:
window.addEventListener(‘load‘, () => {
const images = Array.from(document.querySelectorAll(‘.gallery img‘));
const heights = images.map(img => img.getBoundingClientRect().height);
applyMasonryLayout(heights);
});
Could you do that at DOMContentLoaded? Sometimes. But unless you’ve confirmed all images are loaded (or have explicit width/height), you’ll get incorrect measurements. If layout calculations are central to your design, load is usually a safer signal.
The dangerous middle: thinking one implies the other
The most common mistake I see is using DOMContentLoaded as a proxy for “everything is ready.” It’s not. The DOM exists, but the visuals may not be final. That mistake manifests as:
- Element size read as zero because images aren’t loaded.
- Web fonts not applied, leading to wrong text widths.
- Background images missing during canvas render.
On the flip side, another common mistake is overusing load as a universal “ready” signal. That delays interactivity and makes the page feel slower than it is. I’ve seen checkout flows where a button stays inert for 1–2 seconds because of a slow third-party analytics pixel, even though the UI is visible and the DOM is ready.
How script tags affect the timing
Scripts are the sneakiest factor because they can block or defer DOM parsing. Here’s how different script attributes affect the timeline:
- Plain
scriptwithout attributes: blocks parsing, runs immediately. script defer: downloads in parallel, runs after parsing, beforeDOMContentLoaded.script async: downloads in parallel, runs when ready, potentially before or afterDOMContentLoaded.
This leads to an important nuance: if you rely on DOMContentLoaded but include a slow blocking script, DOMContentLoaded is delayed. If you rely on load, async scripts that load late still delay load if they are referenced as subresources.
Here’s a minimal example showing how deferred scripts influence the event:
document.addEventListener(‘DOMContentLoaded‘, () => {
console.log(‘DOM ready, app.js already executed‘);
});
With defer, app.js executes before DOMContentLoaded, which is typically what you want for DOM initialization. But with async, you can’t assume ordering.
A real-world rule I use
When I’m not sure which event to use, I run this mental checklist:
1) Do I need the DOM structure to exist? If yes, DOMContentLoaded is enough.
2) Do I need images, fonts, or iframes to be fully loaded? If yes, use load.
3) Do I need to respond as soon as the UI is visible? If yes, avoid load.
4) Can I measure layout without waiting for assets? If not, use load or explicit asset checks.
This prevents most timing bugs. It doesn’t replace testing, but it’s a good baseline.
Measuring layout: why images and fonts matter
Layout measurements are the most common reason to wait for load. This is because layout depends on resource dimensions and font metrics. If fonts load after you measure, text width changes. If images load after you measure, element heights change.
A classic example is a hero section with web fonts and a responsive image. On DOMContentLoaded, your code might read h1.offsetWidth or img.offsetHeight and get values based on fallback fonts or empty images. Then, when fonts and images arrive, the dimensions change. That can break things like:
- Scroll-driven animations that depend on element positions.
- Sticky headers that compute offsets.
- In-page anchor offsets for smooth scrolling.
If you cannot wait for full load, you can use a hybrid approach:
document.addEventListener(‘DOMContentLoaded‘, () => {
const hero = document.querySelector(‘.hero‘);
if (!hero) return;
const measure = () => {
const rect = hero.getBoundingClientRect();
console.log(‘Hero size:‘, rect.width, rect.height);
};
// Measure now
measure();
// Re-measure after assets
window.addEventListener(‘load‘, measure);
});
This gives you early data for interactivity and a final correction once the page is fully loaded.
Edge cases that trip teams up
1) Cached assets
If an image is cached, load may fire quickly, but your code may still miss it if you attach the listener too late. In other words, if load already fired, your listener won’t be called. This is more common in single-page apps when reusing a document.
Workaround: check document.readyState and use a fallback.
document.addEventListener(‘DOMContentLoaded‘, () => {
if (document.readyState === ‘complete‘) {
onLoad();
} else {
window.addEventListener(‘load‘, onLoad, { once: true });
}
});
2) Dynamically inserted images
If you insert images after the initial page load, window.load won’t wait for them. The load event only covers resources referenced during initial load. For dynamically inserted images, listen to the image’s own load event.
const img = new Image();
img.src = ‘/dynamic/hero.jpg‘;
img.addEventListener(‘load‘, () => {
console.log(‘Dynamic image loaded‘);
});
3) Fonts that load late
Web fonts can arrive after DOMContentLoaded, which changes text measurements. Modern font loading APIs like document.fonts.ready give a more precise hook than window.load if fonts are the only concern.
document.addEventListener(‘DOMContentLoaded‘, async () => {
await document.fonts.ready;
measureText();
});
4) Third-party widgets
Third-party widgets (chat, ads, analytics) often delay load and create the illusion that “the page is still loading.” I’ve seen chat widgets add 2–3 seconds to load even when the page is otherwise ready. If you use load to trigger core app logic, you inherit those delays.
5) SPA navigations
In single-page apps, DOMContentLoaded fires once for the initial document. For subsequent route changes, you need framework-specific hooks (like router events) or hydration callbacks. The event doesn’t re-fire on SPA navigations.
Practical scenarios: when to use which
Scenario A: Binding a click handler
Use DOMContentLoaded. You want the DOM to exist and interactivity to be immediate.
Scenario B: Initializing a slider with fixed image widths
Use load or per-image load handlers. The slider depends on actual image dimensions.
Scenario C: First contentful paint analytics
Use the Performance API rather than load. load is too late for user-visible milestones.
Scenario D: A/B test DOM mutations
Use DOMContentLoaded if you modify structure. Waiting for load delays the experiment and may bias results.
Scenario E: Screenshot or visual snapshot
Use load and then wait one requestAnimationFrame to ensure the paint is complete.
window.addEventListener(‘load‘, () => {
requestAnimationFrame(() => {
captureScreenshot();
});
});
Performance considerations: perceived speed vs completeness
The choice between DOMContentLoaded and load is also a tradeoff between perceived speed and completeness. Here’s a rough comparison I use when explaining this to teams:
- Using
DOMContentLoadedtypically makes features available 200–800ms earlier on average pages, depending on resource weight. - Using
loadcan lag by 500–2000ms or more, especially when heavy images or third-party scripts are present.
These are ranges, not guarantees, but they illustrate the cost of waiting. For interactive features, the cost is often visible and unnecessary.
I think of it as a “pay for what you need” model. If you don’t need images or fonts, don’t wait for them. If you need them, pay the cost to avoid wrong measurements or flicker.
Common pitfalls (and how I avoid them)
Pitfall 1: Assuming DOMContentLoaded means styles are ready
It doesn’t. Only blocking stylesheets are guaranteed to be parsed before the event. Deferred styles, preloads, and dynamic styles can apply later.
Avoidance: if you depend on styles, confirm that the stylesheet is loaded or rely on load if the cost is acceptable.
Pitfall 2: Binding events in inline scripts before the DOM exists
Inline scripts in the head run before the body is parsed. If they query for body elements, they fail.
Avoidance: either move the script to the end of body, use defer, or wrap in DOMContentLoaded.
Pitfall 3: Waiting for load to start analytics
By the time load fires, you’ve missed the early performance signals. load is a completion signal, not a start signal.
Avoidance: use performance.getEntriesByType(‘navigation‘) and PerformanceObserver for metrics.
Pitfall 4: Ignoring readyState
On some pages, especially with caching, the event may already have fired when you add your listener. If you rely exclusively on an event listener, your initialization might never run.
Avoidance: check document.readyState and run immediately if it is already interactive or complete.
const onDomReady = () => {
// safe DOM init
};
if (document.readyState === ‘loading‘) {
document.addEventListener(‘DOMContentLoaded‘, onDomReady, { once: true });
} else {
onDomReady();
}
Alternative approaches beyond these events
1) defer + module scripts
If your scripts are defer or type="module", they run after parsing without blocking, and the DOM is already built. In many cases, you can skip DOMContentLoaded entirely.
Inside /app.js, you can safely query the DOM because module scripts are deferred by default.
2) Element-level readiness with MutationObserver
If you need to initialize a component that might be injected later (like a lazy-rendered widget), a MutationObserver can watch for that element instead of relying on document-level events.
const observer = new MutationObserver(() => {
const target = document.querySelector(‘.dynamic-widget‘);
if (target) {
initWidget(target);
observer.disconnect();
}
});
observer.observe(document.documentElement, { childList: true, subtree: true });
3) Component-level image readiness
If you only need a specific image, listen to that image’s load event rather than waiting for the entire page.
const img = document.querySelector(‘.hero img‘);
if (img?.complete) {
initHero(img);
} else {
img?.addEventListener(‘load‘, () => initHero(img), { once: true });
}
4) Font readiness via document.fonts
For text-heavy layouts, the font loading API is more precise than waiting for window.load.
await document.fonts.ready;
measureText();
5) Hydration callbacks in modern frameworks
If you use a framework with hydration, prefer its lifecycle hooks. For example, many frameworks expose a “hydrated” or “mounted” callback that indicates the component is ready to handle events. These hooks are often more reliable than document events for SPA routes.
A production checklist I use before choosing
When I’m reviewing code, I ask:
- Is this code about interactivity or layout?
- Does it depend on images, fonts, or iframes?
- Does it run for initial load only, or for SPA navigations too?
- Is it attached in the head or deferred?
- Is it safe if the event already fired?
If the answer is “interactivity only,” DOMContentLoaded (or no event at all with defer) is usually correct. If the answer is “layout depends on assets,” load or asset-specific events are safer.
Case study: fixing the checkout button bug
The checkout button issue I mentioned earlier happened because the script ran in the without defer. It queried #checkout before the element existed and then exited. The fix was to either move the script to the end of body or wrap it in DOMContentLoaded.
The simplest fix was:
Then inside /checkout.js, I could safely do:
const button = document.querySelector(‘#checkout‘);
if (button) button.addEventListener(‘click‘, handleCheckout);
No DOMContentLoaded needed because defer ensures the script runs after parsing. This reduced the chance of future contributors forgetting to wrap their handlers.
Case study: the hero image measurement issue
The hero measurement issue happened because the team measured on DOMContentLoaded. The image had no explicit dimensions, so it wasn’t ready when the DOM was parsed. The fix was to measure after the image loaded, not after the DOM was parsed.
document.addEventListener(‘DOMContentLoaded‘, () => {
const heroImg = document.querySelector(‘.hero img‘);
if (!heroImg) return;
const measure = () => {
const { height } = heroImg.getBoundingClientRect();
layoutHero(height);
};
if (heroImg.complete) {
measure();
} else {
heroImg.addEventListener(‘load‘, measure, { once: true });
}
});
This approach is more precise than window.load because it only waits for the image in question, not every subresource.
The role of readyState
document.readyState is a simple but powerful tool that tells you if the DOM is still loading, interactive, or complete. It’s useful for cases where you might be attaching listeners late.
Values:
loading: the document is still parsing.interactive: the DOM is ready (DOMContentLoadedalready fired or is about to).complete: the document and all resources are fully loaded (loadalready fired).
You can use it as a guard to avoid missing events:
const start = () => {
initDomHandlers();
};
if (document.readyState === ‘loading‘) {
document.addEventListener(‘DOMContentLoaded‘, start, { once: true });
} else {
start();
}
And for load:
const afterLoad = () => {
initAssetDependentWork();
};
if (document.readyState === ‘complete‘) {
afterLoad();
} else {
window.addEventListener(‘load‘, afterLoad, { once: true });
}
Streaming and partial hydration: new constraints
Modern rendering strategies complicate timing. If your HTML is streamed, the DOM is built progressively as chunks arrive. A component may not exist when DOMContentLoaded fires if it’s streamed late, and some frameworks hydrate components after the initial event.
In these cases, I rely on component-level hooks or custom events instead of global document events. For example, a component can dispatch a custom event when it hydrates:
function hydrateWidget() {
// ...hydrate component
window.dispatchEvent(new CustomEvent(‘widget:ready‘));
}
window.addEventListener(‘widget:ready‘, () => {
// safe to access the widget
});
This is more precise than DOMContentLoaded and avoids waiting for full load.
Testing timing decisions in practice
I don’t just rely on theory. I validate timing decisions with real metrics:
- In DevTools, I inspect the Performance timeline to see when
DOMContentLoadedandloadfire relative to user-visible paints. - I record
performance.now()inside the events to compare their distance. - I run throttled network tests to see if
loaddelays become unacceptable.
Example instrumentation:
document.addEventListener(‘DOMContentLoaded‘, () => {
console.log(‘DOMContentLoaded at‘, performance.now());
});
window.addEventListener(‘load‘, () => {
console.log(‘load at‘, performance.now());
});
This gives me real ranges for a page. On image-heavy pages, I’ve seen 1–3 seconds between these events on slow 4G. That’s a huge delay if you’re waiting to enable interactions.
Modern alternatives to avoid global waits
I try to avoid global waits when possible. Instead, I segment by dependency:
- For DOM-only features: run immediately after
DOMContentLoadedor usedefer. - For image-dependent features: wait for specific image
loadevents. - For font-dependent features: use
document.fonts.ready. - For lazy-loaded components: use IntersectionObserver and initialize on demand.
This reduces reliance on a single global event and makes features feel faster.
Practical patterns I reuse
Pattern 1: defer + immediate init
// app.js
initDomFeatures();
This is my default for static pages or server-rendered templates.
Pattern 2: DOM ready wrapper
const onDomReady = (fn) => {
if (document.readyState === ‘loading‘) {
document.addEventListener(‘DOMContentLoaded‘, fn, { once: true });
} else {
fn();
}
};
onDomReady(() => {
bindNav();
bindForms();
});
Pattern 3: Asset-dependent init
const onWindowLoad = (fn) => {
if (document.readyState === ‘complete‘) {
fn();
} else {
window.addEventListener(‘load‘, fn, { once: true });
}
};
onWindowLoad(() => {
initGalleryLayout();
});
Pattern 4: Hybrid measure
document.addEventListener(‘DOMContentLoaded‘, () => {
measureLayout();
window.addEventListener(‘load‘, measureLayout, { once: true });
});
This gives fast start with a final correction.
Production considerations
Deployment
If you deploy code that depends on load, confirm that third-party scripts aren’t delaying it. I’ve seen tracking scripts add seconds to load in production even if staging looked fine.
Monitoring
Log the delta between DOMContentLoaded and load. If the gap widens over time, it indicates heavier resources or slower third parties.
Scaling
On pages that scale in complexity (marketing pages with lots of media), prefer component-level readiness to avoid large delays. A single global load signal becomes less useful as pages grow.
A mental model that helps me teach this
I explain it like this to new developers:
DOMContentLoadedis when the house frame is finished and you can walk inside.loadis when all the furniture and decorations have been delivered.
If you want to wire the lights or open the doors, you only need the frame. If you want to take a photo of the fully furnished room, you need everything in place.
Summary of differences
DOMContentLoadedhappens when HTML parsing is done and the DOM is ready.loadhappens when all subresources are finished loading.- For interactivity,
DOMContentLoadedis typically faster and safer. - For layout measurements that depend on assets,
loador resource-specific events are safer. - Overusing
loadmakes pages feel sluggish; overusingDOMContentLoadedrisks incorrect measurements.
Closing thoughts
When I audit performance and reliability issues, timing is almost always part of the story. Once you internalize that DOMContentLoaded is about structure and load is about completeness, the decision becomes straightforward. I try to keep initialization as early as possible, but no earlier than safe. And when I do need assets, I wait for exactly those assets rather than blocking on the whole page.
In practice, the best approach is rarely “always use DOMContentLoaded” or “always use load.” Instead, I treat these events as two distinct milestones that let me choose the right moment for each piece of logic. That mindset has saved me from countless production bugs and made my pages feel faster without sacrificing correctness.
