JavaScript Document readystatechange Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word READYSTATECHANGE

Definition

The Document readystatechange event fires when document.readyState changes. Typical values: loading, interactive, and complete (MDN). It is not cancelable and does not bubble.

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for readystatechange. Start with this line.

JavaScript
addEventListener("readystatechange", fn)
CallWhat it does
addEventListener("readystatechange", fn)Primary signature.

Built into the browser. Listen with document.addEventListener("readystatechange", …) — no import required.

Library declarations
JavaScript
addEventListener("readystatechange", fn)

Parameters

ParameterDescription
Listener on documentRequired. Event does not bubble (MDN)
Read readyStateRequired. Event itself has no state payload
onreadystatechangeOptional. Handler property (one assignment)

Return Value

Return ValueDescription
*Fires as a Document event (listener receives the Event object).

JavaScript Examples

Example 1 — Log Each readyState

MDN style: print document.readyState whenever the event fires.

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

console.log("script readyState:", document.readyState);
Try It Yourself

How It Works

  1. Listen on document. The event does not bubble (MDN).
  2. Read readyState. The event is a generic Event — state lives on document.
  3. Log transitions. You typically see interactive, then complete.
  4. Timing matters. A late script may already be past earlier states.

Example 2 — Switch on readyState

MDN pattern: branch for loading, interactive (DOM ready), and complete.

JavaScript
function handleReadyState() {
  switch (document.readyState) {
    case "loading":
      console.log("Still loading…");
      break;
    case "interactive":
      console.log("DOM interactive — query elements");
      break;
    case "complete":
      console.log("Complete — resources finished");
      break;
  }
}

document.addEventListener("readystatechange", handleReadyState);
handleReadyState(); // handle current state too
Try It Yourself

How It Works

  1. One handler. Reuse the same function for the event and the current state.
  2. interactive. Safe for most DOM queries (MDN alternative to DOMContentLoaded).
  3. complete. Safe for work that needs images and other sub-resources.
  4. Call immediately. Late scripts may never see earlier transitions.

Example 3 — Wait Until complete

MDN-style alternative to load, with a late-script safe guard.

JavaScript
function onComplete() {
  console.log("Page complete — safe for full-resource work");
}

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

How It Works

  1. Check first. If already complete, run immediately.
  2. Else listen. Wait for the transition to complete.
  3. Filter. Ignore interactive if you only want full resources.
  4. Use case. Measuring layout that depends on images, or post-load cleanup.
Compatibility

Browser Support

Document readystatechange is Baseline Widely available (MDN, since July 2015). It is a standard Document event — not Deprecated, Experimental, or Non-standard.

✓ Baseline · Widely available

Document readystatechange

Fires when document.readyState changes. Listen on document — the event does not bubble.

99% Modern browser support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
readystatechange Excellent

Bottom line: Safe for virtually all browsers students use today. Pair with document.readyState, and guard late scripts so you do not miss interactive or complete.

Frequently Asked Questions

It fires when the Document readyState attribute has changed. Typical values are loading, interactive, and complete. Read document.readyState inside the handler to see the new state (MDN).
No. MDN marks Document readystatechange as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
No. MDN states the event is not cancelable and does not bubble. Listen on document.
readyState moves loading → interactive → complete. DOMContentLoaded is closely tied to interactive (after deferred/module scripts). The window load event is closely tied to complete (MDN).
Yes. You can use document.onreadystatechange or document.addEventListener("readystatechange", …).
Use DOMContentLoaded when you only care that the DOM is ready. Use readystatechange when you want every readyState transition, or a switch on loading / interactive / complete (MDN).

Next: scroll

Learn the Document event that fires when the document is scrolled.

scroll tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document prerenderingchange Event JavaScript Document scroll Event