jQuery holdReady() Method

What Is jQuery.holdReady()?

jQuery.holdReady(hold) (since 1.6) delays or releases jQuery’s document ready event. Pass true to hold, false to release one hold. It is deprecated since 3.2 but still works in jQuery 3.x.

// Deprecated (since 3.2) — call early, before ready fires
$.holdReady(true);   // delay ready
$.holdReady(false);  // release one hold

// Modern replacement
$.when($.ready, customPromise)
  .then(function () {
    // main code
  })
  .catch(function (error) {
    // handle errors
  });

How to Use holdReady()

Call early, pair every hold with a release, and prefer $.when for new work.

1. Call $.holdReady(true) in the <head> right after the jQuery script tag.
2. Load plugins or other async work (for example with $.getScript).
3. Call $.holdReady(false) when that work finishes — one release per hold.
4. Register ready handlers with $(function () { … }) as usual; they wait while held.
5. In new code, replace the global switch with $.when($.ready, promise).

Pseudocode

call $.holdReady(true) early
    → holdCount = holdCount + 1
    → ready handlers wait

load plugin / async work

call $.holdReady(false)
    → holdCount = holdCount - 1

when holdCount === 0 and DOM is ready:
    fire jQuery ready
    run all $(function () { ... }) handlers

if holdReady(true) after ready already fired:
    no effect

modern path:
    $.when($.ready, customPromise).then(main)

Cheat Sheet

Quick facts for reading or migrating legacy holdReady code.

Live Preview

This page’s ready event already fired, so the demo simulates hold/release timing and the modern $.when pattern.

Ready — pick an action and click Run.

jQuery Examples

Short demos of the legacy API and the modern replacement. Prefer $.when for new projects.

$.holdReady(true);
$.getScript("myplugin.js", function () {
  $.holdReady(false);
});

$(function () {
  MyPlugin.init();
});

Ready waits while the script loads
Then MyPlugin.init() runs

$.holdReady(true);

$(function () {
  $("#out").text("Ready handler ran after release");
});

setTimeout(function () {
  $.holdReady(false);
}, 800);

~800ms later →
Ready handler ran after release

$.holdReady(true);
$.holdReady(true);

$(function () {
  $("#out").text("Ready finally runs");
});

$.holdReady(false); // still held
$.holdReady(false); // now ready can fire

After first release — still waiting
After second release → Ready finally runs

var pluginReady = $.Deferred();

setTimeout(function () {
  window.MyPlugin = { init: function () { return "ok"; } };
  pluginReady.resolve();
}, 400);

$.when($.ready, pluginReady).then(function () {
  $("#out").text("Init: " + MyPlugin.init());
});

Init: ok
(runs after both DOM ready and the promise resolve)

$(function () {
  $("#out").append("Ready already ran. ");
  $.holdReady(true);
  $("#out").append("holdReady(true) after ready — no effect. ");
  $(function () {
    $("#out").append("Inner handler still runs immediately.");
  });
});

Ready already ran. holdReady(true) after ready — no effect. Inner handler still runs immediately.

Performance Notes

Holding ready does not slow the network by itself — it delays your init code. Keep holds short and always release them.

Key Takeaways