JavaScript Document readyState Property

What You’ll Learn

Document.readyState is a read-only instance property that returns the page loading phase: "loading", "interactive", or "complete". Learn MDN’s switch pattern, readystatechange, and alternatives to DOMContentLoaded and load with five examples.

Introduction

When a web page loads, the browser moves through distinct phases: parsing HTML, building the DOM, fetching images and stylesheets, and firing load events. document.readyState exposes where the document is in that pipeline right now.

MDN: the property describes the loading state of the document. When its value changes, a readystatechange event fires on the document object.

Related Document tutorials: hidden, currentScript, body, Document constructor.

Understanding Document.readyState

A read-only instance property on Document. Its value is always one of three strings defined by HTML (MDN).

• "loading" — document still loading; HTML parser active (MDN).
• "interactive" — document parsed; deferred/module scripts run; DOMContentLoaded fires (MDN).
• "complete" — document and sub-resources loaded; load event about to fire (MDN).
• Event — readystatechange on each transition (MDN).
• Status — Baseline Widely available since July 2015 (MDN).

📝 Syntax

document.readyState

Value

A string: "loading", "interactive", or "complete" (MDN).

MDN example — switch on readiness

switch (document.readyState) {
  case "loading":
    // The document is loading.
    break;
  case "interactive": {
    // DOM parsed; sub-resources may still load.
    const span = document.createElement("span");
    span.textContent = "A <span> element.";
    document.body.appendChild(span);
    break;
  }
  case "complete":
    // The page is fully loaded.
    console.log("Page complete");
    break;
}

⚖️ Loading Signals

Examples Gallery

Examples follow MDN Document: readyState. In try-it labs the page is usually already complete when the script runs.

console.log(document.readyState);
// "complete" after full load (typical in try-it)

complete

switch (document.readyState) {
  case "loading":
    console.log("Still loading");
    break;
  case "interactive":
    console.log("DOM ready");
    break;
  case "complete":
    console.log("Fully loaded");
    break;
}

Fully loaded

document.onreadystatechange = () => {
  if (document.readyState === "interactive") {
    initApplication();
  }
};

initApplication() when interactive (or already past that state)

document.onreadystatechange = () => {
  if (document.readyState === "complete") {
    initApplication();
  }
};

initApplication() when complete

document.addEventListener("readystatechange", (event) => {
  if (event.target.readyState === "interactive") {
    initLoader();
  } else if (event.target.readyState === "complete") {
    initApp();
  }
});

initLoader at interactive
initApp at complete

🚀 Common Use Cases

• Boot apps early — start DOM work at interactive.
• Defer heavy work — wait for complete before measuring layout.
• Debug load timing — log each readystatechange transition.
• Legacy compatibility — single handler instead of multiple events.
• Inline script guards — check state before touching document.body.
• Progress UI — update a loader as state advances.

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• Read-only string; assigning does not change browser load behavior.
• readystatechange fires on document, not window (MDN).
• For most apps, DOMContentLoaded and load remain the clearest APIs.
• Related: currentScript, hidden, Document constructor.

💡 Best Practices