JavaScript Document readystatechange Event

What You’ll Learn

The Document readystatechange event fires whenever document.readyState changes. Learn the loading → interactive → complete path, how it relates to DOMContentLoaded and load, and five try-it labs.

Introduction

As a page loads, the Document moves through a small set of loading states stored in document.readyState. Each time that value changes, the browser fires readystatechange on the Document.

That makes the event a progress signal: “the document is still loading,” “the DOM is interactive,” or “loading is complete.” You still read document.readyState inside the handler—the event itself does not carry the new state as a separate property.

Understanding readystatechange

A standard Document event that answers: “Did document.readyState just change?”

• Fires when the Document readyState attribute changes (MDN).
• Not cancelable and does not bubble — listen on document.
• Event type — a generic Event.
• Handler — document.onreadystatechange or addEventListener("readystatechange", ...).
• States — commonly loading, interactive, complete.
• Status — Baseline Widely available since July 2015 (MDN).

📝 Syntax

Use the event name with addEventListener, or set the handler property on document:

addEventListener("readystatechange", (event) => { });

onreadystatechange = (event) => { };

Event type

A generic Event. Not cancelable and does not bubble.

MDN-style log

document.addEventListener("readystatechange", (event) => {
  console.log("readystate: " + document.readyState);
});

document.addEventListener("DOMContentLoaded", (event) => {
  console.log("DOMContentLoaded");
});

window.addEventListener("load", (event) => {
  console.log("load");
});

readyState values

⚖️ readystatechange vs DOMContentLoaded vs load

Examples Gallery

Examples follow MDN Document: readystatechange event. In try-it labs the document is often already complete, so you may see the current state immediately—reload or log early to catch earlier transitions.

const log = document.getElementById("log");

document.addEventListener("readystatechange", () => {
  log.textContent += "readystate: " + document.readyState + "\n";
});

readystate: interactive
readystate: complete

const out = document.getElementById("out");

document.onreadystatechange = () => {
  out.textContent = "readyState is now: " + document.readyState;
};

// Also show the current value immediately
out.textContent = "readyState is now: " + document.readyState;

readyState is now: complete

const out = document.getElementById("out");

function handleReadyState() {
  switch (document.readyState) {
    case "loading":
      out.textContent = "Still loading…";
      break;
    case "interactive":
      out.textContent = "DOM interactive — safe to query elements";
      break;
    case "complete":
      out.textContent = "Complete — images and other resources finished";
      break;
  }
}

document.addEventListener("readystatechange", handleReadyState);
handleReadyState(); // handle current state if event already passed

Complete — images and other resources finished

const log = document.getElementById("log");

document.addEventListener("readystatechange", () => {
  log.textContent += "readystate: " + document.readyState + "\n";
});

document.addEventListener("DOMContentLoaded", () => {
  log.textContent += "DOMContentLoaded\n";
});

window.addEventListener("load", () => {
  log.textContent += "load\n";
});

log.textContent += "script ran; readyState=" + document.readyState + "\n";

script ran; readyState=loading
readystate: interactive
DOMContentLoaded
readystate: complete
load

const out = document.getElementById("out");

function onComplete() {
  out.textContent = "Page complete — safe for full-resource work";
}

if (document.readyState === "complete") {
  onComplete();
} else {
  document.addEventListener("readystatechange", () => {
    if (document.readyState === "complete") onComplete();
  });
}

Page complete — safe for full-resource work

🚀 Common Use Cases

• Logging or debugging document load progress.
• Switching UI copy as the page moves to interactive / complete.
• Running different init steps per readyState value.
• Guarding late scripts so they still run after the document is ready.
• Teaching how DOMContentLoaded and load fit the state path.

🔧 How It Works

📝 Notes

• Baseline Widely available (since July 2015)—no Deprecated / Experimental / Non-standard banner.
• Not cancelable and does not bubble—listen on document.
• Always read document.readyState in the handler for the new value.
• Late scripts may miss early transitions—check the current state once on startup.
• Related learning: readyState, DOMContentLoaded, JavaScript hub.

💡 Best Practices