jQuery jQuery.ready Property

What You’ll Learn

The jQuery.ready property is a thenable that resolves when the DOM is safe to manipulate. This tutorial covers the official jQuery.when patterns, how it relates to $(function(){}) and .ready(), combining ready with Ajax, and modern Promise.resolve usage in jQuery 3.0+.

Introduction

jQuery code usually needs to wait until the browser has parsed the HTML before selecting elements, attaching events, or changing the DOM. The familiar shorthand $(function(){ ... }) registers a callback for that moment.

Under the hood, jQuery exposes jQuery.ready — a Promise-like object you can pass to jQuery.when() or native promise helpers. It resolves once the document is ready, letting you coordinate DOM setup with other asynchronous tasks such as $.getJSON() in a single .done() handler.

If you are new to jQuery, start with $(function(){}) for everyday page setup. Reach for jQuery.ready when you need promise-style composition — the patterns shown in the official jQuery documentation since version 1.8.

Understanding the jQuery.ready Property

jQuery.ready is not a function you call. It is a thenable — an object with a .then() method that fulfills when jQuery’s internal ready list fires. The .ready( handler ) method on collections uses this same mechanism to queue and run your callbacks.

As of jQuery 3.0, the documentation warns not to assume jQuery.ready is a jQuery.Deferred or a native Promise. Code should treat it as an opaque ready signal compatible with jQuery.when and Promise.resolve().

📝 Syntax

Access the global ready thenable — no arguments:

jQuery.ready
// or
$.ready

Official usage patterns

// Pattern 1 — listen for document ready (jQuery 1.8+)
$.when( $.ready ).then(function () {
  // Document is ready.
});

// Pattern 2 — wait for Ajax AND ready (official demo)
$.when(
  $.getJSON( "ajax/test.json" ),
  $.ready
).done(function ( data ) {
  // Document is ready.
  // Value of test.json is passed as data.
});

// Pattern 3 — jQuery 3.0+ with native Promise
Promise.resolve( $.ready ).then(function () {
  // Document is ready.
});

Return value

• A thenable object that resolves when the DOM is ready.
• No value is passed to .then() handlers — the signal itself means “ready.”
• Related callback API: $(function(){ ... }) and $(document).ready(fn).

Examples Gallery

Examples follow the official jQuery.ready documentation. Use jQuery 3.7.1 in DevTools or the Try-it links.

$.when( $.ready ).then(function () {
  // Document is ready.
  $("#status").text("The DOM is now loaded and can be manipulated.");
});

The DOM is now loaded and can be manipulated.

$.when(
  $.getJSON( "ajax/test.json" ),
  $.ready
).done(function ( data ) {
  // Document is ready.
  // Value of test.json is passed as data.
  $("#list").empty();
  $.each( data.items, function ( i, item ) {
    $("#list").append( "<li>" + item + "</li>" );
  });
});

List populated after both JSON and DOM are ready

Promise.resolve( $.ready ).then(function () {
  document.body.classList.add("dom-ready");
});

// async/await style
async function init() {
  await Promise.resolve( $.ready );
  console.log("DOM ready via async/await");
}
init();

dom-ready class added
DOM ready via async/await

// Recommended since jQuery 3.0
$(function () {
  // Handler for .ready() called.
  $("p").text("The DOM is now loaded and can be manipulated.");
});

// Equivalent long form
$(document).ready(function () {
  // Same timing as above.
});

The DOM is now loaded and can be manipulated.

// Simulate script loaded after DOM is already parsed
setTimeout(function () {
  $.when( $.ready ).then(function () {
    console.log("jQuery ready still runs late");
  });

  // Native listener added too late — never fires if event passed
  document.addEventListener("DOMContentLoaded", function () {
    console.log("This often never runs when registered late");
  });
}, 0);

jQuery ready still runs late
(late DOMContentLoaded listener silent)

🚀 Common Use Cases

• Ajax + DOM gate — $.when($.getJSON(url), $.ready) before building UI.
• Plugin initialization — ensure DOM exists before .append() or .on().
• Promise pipelines — chain ready with other thenables in jQuery 3 apps.
• Dynamic script tags — late-loaded jQuery still runs ready handlers.
• Module bundlers — defer entry until Promise.resolve($.ready).
• Testing — await ready before asserting on DOM fixtures.

📝 Notes

• Added in jQuery 1.8 — still supported in jQuery 3.7.x.
• Not the same as the removed event-handler overload of .toggle() or $(document).on("ready") (removed in 3.0).
• Since jQuery 3.0, only $(handler) shorthand is recommended for callbacks — not $("img").ready(handler).
• Do not attach window load listeners inside a ready handler expecting them to run if load already fired.
• Related: jQuery.holdReady() can pause ready (advanced), jQuery.isReady reports state.
• Place scripts at end of <body> or use defer — ready helps but clean HTML order still matters.

💡 Best Practices