DOM Ready in Vanilla JavaScript: DOMContentLoaded and Alternatives

The vanilla JavaScript equivalent of jQuery's document-ready callback is usually the DOMContentLoaded event. It fires when the browser has parsed the HTML and built the DOM, so JavaScript can safely find and update page elements. You will also learn when to use load, how defer can remove the need for a ready listener, and how to handle code that may run after the DOM is already ready.

$(document).ready(...) is a jQuery convenience for waiting until the DOM is ready.

In modern browser JavaScript, listen for the DOMContentLoaded event:

document.addEventListener("DOMContentLoaded", function () {
  myFunction();
});

The DOM (Document Object Model) is the browser's JavaScript representation of the HTML page. Before the browser has parsed an element, code such as this may fail because the element does not exist yet:

const button = document.querySelector("#save-button");

DOMContentLoaded means:

• The HTML has been parsed.
• DOM elements are available to query and modify.
• Deferred scripts have run.
• Images, stylesheets, fonts, videos, and other external resources may still be loading.

This distinction matters because many page-initialization tasks need elements to exist, but do not need every image or external resource to finish downloading.

For nearly all supported modern browsers, DOMContentLoaded is the correct replacement for a jQuery ready callback.

Think of a web page as a building being assembled.

• HTML parsing is the construction crew placing rooms, doors, and furniture into the building plan.
• The DOM is the completed floor plan that JavaScript can inspect and change.
• DOMContentLoaded is the announcement: “The building layout is complete; you can start arranging things.”
• window.load is the later announcement: “Everything has arrived, including paintings, appliances, and decorations.”

If your code only needs to find a button and attach a click handler, wait for the layout (DOMContentLoaded), not every decorative resource (load).

Use addEventListener to register a callback for DOMContentLoaded:

document.addEventListener("DOMContentLoaded", function () {
  console.log("The DOM is ready.");
});

An arrow function works too:

document.addEventListener("DOMContentLoaded", () => {
  const message = document.querySelector("#message");
  message.textContent = "JavaScript started after the DOM was ready.";
});

Given this HTML:

<p id="message">Loading...</p>

the callback can safely select #message because the browser has finished parsing the document before it runs.

A reusable whenDomReady helper

Sometimes a script may be loaded after DOMContentLoaded has already fired. Check document.readyState so the callback runs in both cases:

function whenDomReady(callback) {
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", callback, { once: true });
  } else {
    callback();
  }
}

whenDomReady(() => {
  console.log("Safe to use the DOM.");
});

document.readyState can be:

• "loading": HTML parsing is still in progress.
• "interactive": the DOM has been parsed.
• "complete": the page and its dependent resources have finished loading.

If the state is not "loading", the DOM is already usable.

Consider this page:

<!doctype html>
<html lang="en">
  <head>
    <script>
      document.addEventListener("DOMContentLoaded", () => {
        const status = document.querySelector("#status");
        status.textContent = "Ready";
      });
    </script>
  </head>
  <body>
    <p id="status">Waiting...</p>
  </body>
</html>

Execution sequence:

1. The browser starts parsing the HTML.
2. It reaches the <script> in <head>.
3. The script registers a DOMContentLoaded listener, then finishes. It does not try to select #status yet.
4. The browser continues parsing and creates <p id="status"> in the DOM.
5. HTML parsing finishes.
6. The browser dispatches DOMContentLoaded.
7. The callback runs, finds #status, and changes its text to Ready.

If the script called document.querySelector("#status") immediately in the <head>, it would run before the browser had parsed the <p> element. The result would be null.

Use DOM-ready logic when your code depends on page elements being present:

• Form behavior: attach submit, input, or change listeners after locating a form.
• Navigation menus: initialize a mobile-menu button and its panel.
• Client-side validation: find required fields and show validation messages.
• Dashboard widgets: populate tables, charts, counters, or filters after their containers exist.
• Accessibility enhancements: set focus, update ARIA attributes, or add keyboard handlers.
• Progressive enhancement: turn server-rendered HTML into tabs, accordions, modals, or interactive components.

Use the load event instead when the actual dimensions or full availability of resources are required. For example, an image-processing script may need an image to finish loading before reading its natural size.

In current projects, developers often avoid a global “ready” wrapper by loading scripts with defer:

<script src="app.js" defer></script>

A deferred external script runs after HTML parsing is complete, so app.js can usually access DOM elements directly:

const menuButton = document.querySelector("#menu-button");
const menu = document.querySelector("#menu");

menuButton.addEventListener("click", () => {
  menu.hidden = !menu.hidden;
});

Common project patterns include:

• Component initialization: find all matching elements and initialize each one.

  document.querySelectorAll("[data-tabs]").forEach((tabsElement) => {
    initializeTabs(tabsElement);
  });
  

• Guard clauses: skip setup when a component is not present on the current page.

  const searchForm = document.querySelector("#search-form");
  if (!searchForm) {
    // This page does not contain the search form.
  } else {
    initializeSearch(searchForm);
  }
  

• Event delegation: attach one listener to an existing parent rather than attaching listeners to every child.

  document.addEventListener("click", (event) => {
    if (event.target.matches("[data-dismiss]")) {
      event.target.closest(".alert")?.remove();
    }
  });
  

• Async data loading: wait for the DOM before displaying fetched API data in an existing container.

For new code, prefer external JavaScript files and addEventListener over inline attributes such as <body onload="...">.

Selecting elements too early

This script is in <head>, but the button appears later in <body>:

const button = document.querySelector("#save-button");
button.addEventListener("click", save);

button may be null, causing an error. Fix it by using DOMContentLoaded, adding defer to the external script, or placing a non-deferred script after the relevant HTML.

Using window.onload for DOM-only work

window.addEventListener("load", initializeMenu);

This works, but it waits for images and other resources too. For normal DOM setup, prefer:

document.addEventListener("DOMContentLoaded", initializeMenu);

Overwriting another handler

window.onload = initializeMenu;
window.onload = initializeAnalytics;

The second assignment replaces the first one. Use addEventListener so multiple listeners can coexist:

window.addEventListener("load", initializeMenu);
window.addEventListener("load", initializeAnalytics);

Using the wrong jQuery selector

The jQuery form is $(document).ready(...), not $('document').ready(...). The latter looks for an HTML element named document.

Assuming a late listener will fire

If a dynamically loaded script adds a DOMContentLoaded listener after the event has already happened, its callback will never run. Use a readyState check, such as the whenDomReady helper shown earlier.

Relying on inline event attributes

<body onload="myFunction()">

This mixes markup and behavior, is harder to maintain, and makes it less convenient to add independent handlers. Prefer JavaScript with addEventListener.

DOMContentLoaded versus load

DOMContentLoaded answers: “Can I access the HTML elements yet?”

load answers: “Has the entire page, including dependent resources, finished loading?”

// Standard DOM-ready listener
document.addEventListener("DOMContentLoaded", initialize);

function initialize() {
  // Query and modify DOM elements here.
}

<!-- Preferred way to load an external app script -->
<script src="app.js" defer></script>

// Safe even if the DOM may already be ready
function whenDomReady(callback) {
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", callback, { once: true });
  } else {
    callback();
  }
}

// Use only when all page resources must be finished
window.addEventListener("load", () => {
  // Image-size-dependent code, for example.
});

Rules:

• Use DOMContentLoaded for normal DOM initialization.
• Use defer for external scripts that should run after parsing.
• Use addEventListener, not window.onload = ..., when multiple handlers may exist.
• Use load only when the full resource load matters.
• Check document.readyState if a script can load late.

What is the vanilla JavaScript equivalent of $(document).ready()?

Use document.addEventListener("DOMContentLoaded", callback). It runs the callback after the HTML has been parsed into a DOM.

Is DOMContentLoaded the same as window.onload?

No. DOMContentLoaded occurs after HTML parsing. load occurs later, after dependent resources such as images have loaded.

Do I need DOMContentLoaded when my script uses defer?

Usually no. A deferred external script runs after document parsing, so DOM elements are available. You may still use a listener if it makes the initialization timing clearer.

Can I put a script at the bottom of the body instead?

Yes. A script after the elements it uses can access those elements. However, an external script with defer is often easier to organize and keeps script-loading behavior explicit.

Why does my DOMContentLoaded callback not run?

It may have been registered after the event already fired. Check document.readyState; if it is not "loading", call the initialization function immediately.

Can more than one DOMContentLoaded handler be added?

Yes. Each addEventListener("DOMContentLoaded", callback) call adds another listener.

Do images delay DOMContentLoaded?

Images generally do not need to finish loading before DOMContentLoaded fires. If your logic depends on loaded images, use an image-specific load listener or the window load event.

• DOM manipulation — selecting, creating, and changing HTML elements after the DOM is available.
• JavaScript events — DOMContentLoaded, load, click, and other browser notifications use the event system.
• Script loading (async and defer) — script attributes control when external JavaScript downloads and executes.
• Event listeners — addEventListener lets multiple independent parts of an application respond to events.
• Document readyState — indicates whether the document is loading, interactive, or complete.
• Event delegation — attach handlers to a stable parent element, especially for dynamically added content.
• Progressive enhancement — start with usable HTML, then add JavaScript behavior when the page is ready.