jQuery.holdReady() Method

Beginner

⏱️ 10 min read

📚 Updated: Jul 2026

🎯 5 Examples

🚀 5 Try-it labs

Ready control

Overview

What You’ll Learn

The jQuery.holdReady() method pauses or releases jQuery’s document ready event — letting dynamic script loaders finish before $(function(){}) handlers run. This tutorial covers the official $.getScript pattern, multiple hold counters, deprecation in 3.2, and the modern $.when($.ready, promise) replacement.

hold

Boolean arg

true

Pause ready

false

Release

Since 1.6

Added

Deprecated

Since 3.2

$.when

Modern fix

Fundamentals

Introduction

Most jQuery pages wait for the DOM with $(function(){ ... }). That works when all scripts are loaded synchronously in order. But what if a bootstrap script must fetch a plugin with $.getScript() before the rest of your app initializes?

jQuery 1.6 added jQuery.holdReady(hold) as a global pause switch. Call $.holdReady(true) early to block the ready event, load extra JavaScript, then call $.holdReady(false) when plugins are available. Only then do queued ready handlers run.

This is an advanced API. jQuery deprecated it in 3.2 because explicit promise composition is clearer. You should understand holdReady when maintaining legacy loaders — and use $.when($.ready, customPromise) in new projects.

Concept

Understanding the `jQuery.holdReady()` Method

jQuery.holdReady(hold) accepts a Boolean. Passing true requests a hold — jQuery will not fire the ready event even if the DOM is parsed. Passing false releases one hold. Ready fires only when the hold counter returns to zero and the document satisfies normal ready conditions.

The method returns undefined. It does not chain. It must be invoked from an inline script in the <head> (or very early in the body) before ready would otherwise occur — calling it after ready already fired has no effect.

⚠️

Deprecation notice

Since jQuery 3.2, prefer $.when($.ready, customPromise).then(fn) over global ready holds. See the official migration guidance on the jQuery API page.

Foundation

📝 Syntax

Pause or release the ready event with a Boolean flag:

jQuery

jQuery.holdReady( hold )
// or
$.holdReady( hold )

Parameters

hold (Boolean) — true adds a hold; false releases one hold.

Return value

undefined

Official plugin-load pattern

jQuery

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

Modern replacement (jQuery 3.2+)

jQuery

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

Cheat Sheet

⚡ Quick Reference

Call	Effect
`$.holdReady(true)`	Add one hold — delay ready
`$.holdReady(false)`	Release one hold
Multiple `true` calls	Need matching `false` count
After ready fired	No effect
Return value	`undefined`
Modern alternative	`$.when($.ready, promise)`

Compare

📋 `holdReady` vs `$.when($.ready, promise)`

Both delay app init until extra async work finishes — the modern pattern is explicit and local.

holdReady

global hold

Deprecated 3.2

$.when

local promise

Recommended

$(fn)

no extra wait

Default init

$.ready

thenable

Compose timing

Hands-On

Examples Gallery

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

📚 Getting Started

Official pattern — hold ready until a script finishes loading.

Example 1 — Official `$.getScript` Plugin Demo

Delay ready until myplugin.js loads — from the jQuery API docs.

jQuery

// In <head>, immediately after jQuery
$.holdReady( true );
$.getScript( "myplugin.js", function() {
  $.holdReady( false );
});

// Later, in your app bundle
$(function () {
  MyPlugin.init(); // safe — plugin loaded before ready ran
});

Try It Yourself

How It Works

The hold prevents $(function(){}) from executing while getScript is in flight — even if the HTML DOM is already parsed underneath.

📈 Practical Patterns

Observe delayed handlers, stacked holds, modern migration, and late-call pitfalls.

Example 2 — Ready Handlers Wait While Held

Log timestamps to see ready callbacks deferred until holdReady(false).

jQuery

$.holdReady( true );

$(function () {
  console.log("Ready handler at", Date.now());
});

setTimeout(function () {
  console.log("Releasing hold at", Date.now());
  $.holdReady( false );
}, 800);

Try It Yourself

How It Works

Ready handlers queue normally but jQuery withholds execution until all holds clear. The handler timestamp matches the release, not DOM parse time.

Example 3 — Multiple Holds Need Matching Releases

Two true calls require two false calls before ready fires.

jQuery

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

$(function () {
  console.log("Ready finally runs");
});

$.holdReady( false ); // still held — one hold remains
console.log("After first release — ready not yet");

setTimeout(function () {
  $.holdReady( false ); // second release — ready can fire
}, 200);

Try It Yourself

How It Works

jQuery tracks a hold counter internally. Forgetting a matching false leaves ready blocked forever — a common bug when multiple loaders each call holdReady(true).

Example 4 — Modern `$.when` Replacement (Recommended)

Official migration pattern — wait for DOM ready and a custom promise without global holds.

jQuery

var pluginReady = $.Deferred();

$.getScript( "myplugin.js", function () {
  pluginReady.resolve();
});

$.when( $.ready, pluginReady )
  .then(function () {
    MyPlugin.init();
  })
  .catch(function (error) {
    console.error("Init failed", error);
  });

Try It Yourself

How It Works

No global side effects — other code can still use $(fn) independently. Your init block explicitly waits for both conditions, with .catch for load failures.

Example 5 — Calling `holdReady` After Ready Has No Effect

Attempting to hold after the ready event already fired does nothing.

jQuery

$(function () {
  console.log("Ready already ran");

  // Too late — ready event passed
  $.holdReady( true );
  console.log("holdReady(true) after ready — no effect");

  $(function () {
    console.log("This inner handler still runs immediately");
  });
});

Try It Yourself

How It Works

That is why the docs insist on calling holdReady(true) in the head right after jQuery loads. Dynamic holds mid-page cannot rewind ready.

Applications

🚀 Common Use Cases

Dynamic plugin loaders — block ready until $.getScript finishes (legacy pattern).
Concatenated bundle bootstraps — head inline script holds while modules register.
Third-party widget hosts — ensure dependency scripts exist before init handlers.
Reading old jQuery plugins — recognize hold/release in vendor code during upgrades.
Migrating to $.when — replace global holds with explicit promise gates.
Debugging stuck pages — unmatched holdReady(true) leaves ready never firing.

🧠 How `holdReady` Gates the Ready Event

Early hold

$.holdReady(true) in head — counter increments.

Hold

DOM parses

HTML ready, but jQuery withholds firing ready handlers.

Wait

Async work

$.getScript or other loader runs; calls holdReady(false).

Load

Ready fires

Counter zero + DOM ready — $(fn) and $.ready resolve.

Important

📝 Notes

Added in jQuery 1.6; deprecated in jQuery 3.2 — still present in 3.7.x.
Must be called before ready fires — typically right after the jQuery script tag.
Each true needs a matching false or ready never runs.
Related: jQuery.ready, jQuery.isReady, .ready().
Modern apps: ES modules and type="module" defer naturally — rarely need holdReady.
Prefer $.when($.ready, promise) for new code — clearer error handling with .catch.

Compatibility

Browser Support

jQuery.holdReady() works wherever jQuery runs. Added in jQuery 1.6, deprecated in jQuery 3.2. Behavior is identical across browsers because it is jQuery-internal ready scheduling.

✓ Deprecated 3.2

jQuery jQuery.holdReady()

Supported in jQuery 1.x, 2.x, and 3.x. Use $.when($.ready, promise) in new projects instead of global holds.

100% With jQuery loaded

Google Chrome All versions · Desktop & Mobile

Full support

Mozilla Firefox All versions · Desktop & Mobile

Full support

Apple Safari All versions · macOS & iOS

Full support

Microsoft Edge All versions · Chromium & Legacy

Full support

Internet Explorer IE 6+ · Legacy environments

Full support

Opera All modern versions

Full support

jQuery.holdReady() Legacy API

Bottom line: Understand holdReady for maintaining legacy loaders. Default to explicit promise composition for new initialization code.

Wrap Up

Conclusion

jQuery.holdReady(hold) is a global pause switch for jQuery’s ready event — born for dynamic script loaders that had to fetch plugins before page initialization. Call true early, release with false, and match every hold with a release.

jQuery deprecated the API in 3.2 because $.when($.ready, customPromise) is clearer and safer. Learn holdReady to read legacy code; write new bootstraps with explicit promises instead.

View Examples Gallery Previous: .ready() Next: jQuery.noConflict()

Pro Tips

💡 Best Practices

✅ Do

Use $.when($.ready, promise) in new jQuery 3.2+ code
Call holdReady(true) immediately after jQuery in head (legacy only)
Release with holdReady(false) in getScript callbacks
Match every true with a false
Add .catch when plugin load can fail

❌ Don’t

Use holdReady in greenfield apps without a legacy reason
Call holdReady(true) after ready already fired
Forget a release — ready handlers never run
Block all page init globally when one module needs a delay
Assume holdReady works with native ES module graphs

Summary

Key Takeaways

Knowledge Unlocked

Five things to remember about `jQuery.holdReady()`

Pause and release the global ready event.

Core concepts

⏸ 01

true/false

Hold/release

API

📄 02

Early

In head

Timing

2× 03

Counter

Match pairs

Pitfall

3.2 04

Deprecated

Since 3.2

Migrate

🔄 05

$.when

Replace

Modern

❓ Frequently Asked Questions

What does jQuery.holdReady() do?

jQuery.holdReady(hold) pauses or releases jQuery's document ready event. Pass true to delay ready handlers from running; pass false to release one hold. Added in jQuery 1.6 for dynamic script loaders that need plugins loaded before page init.

Is jQuery.holdReady() deprecated?

Yes. jQuery.holdReady() was deprecated in jQuery 3.2. The official docs recommend explicit waiting with $.when($.ready, customPromise).then(...) instead of a global ready switch. It still works in jQuery 3.7.x but should not appear in new code.

When must I call jQuery.holdReady(true)?

Early in the document — typically in the head immediately after the jQuery script tag, before DOM ready fires. If you call holdReady(true) after the ready event already ran, it has no effect.

Can I call holdReady(true) multiple times?

Yes. Each holdReady(true) increments an internal counter. Ready does not fire until every hold is released with a matching holdReady(false) and normal DOM ready conditions are met.

What should I use instead of holdReady in modern jQuery?

Use $.when($.ready, yourPromise).then(function(){ /* main code */ }).catch(function(err){ /* errors */ }). Build a Deferred or Promise for your custom async work — getScript, dynamic imports, or module loading — and compose it with $.ready.

How is holdReady related to jQuery.ready?

jQuery.ready is the thenable that resolves when ready fires. holdReady blocks that resolution until holds are released. While held, $(function(){}) callbacks and $.when($.ready) handlers wait even if the HTML DOM is already parsed.

Did you know?

Before holdReady, developers sometimes placed jQuery plugins synchronously in the head to guarantee they existed before body scripts ran. holdReady let loaders switch to async $.getScript without race conditions against $(fn). jQuery 3.2’s deprecation pushed the ecosystem toward composing $.ready with local Deferreds — the same promise mindset jQuery uses elsewhere for Ajax — instead of one global flag that could accidentally freeze every ready handler on the page.

Next: jQuery .load() Method

Load HTML from the server and inject it into the DOM with Ajax.

.load() tutorial →

About the author

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)

6 people found this page helpful

jQuery .ready() Method jQuery.noConflict() Method

jQuery.holdReady() Method

What You’ll Learn

hold

true

false

Since 1.6

Deprecated

$.when

Introduction

Understanding the jQuery.holdReady() Method

📝 Syntax

Parameters

Return value

Official plugin-load pattern

Modern replacement (jQuery 3.2+)

⚡ Quick Reference

📋 holdReady vs $.when($.ready, promise)

Examples Gallery

📚 Getting Started

Example 1 — Official $.getScript Plugin Demo

How It Works

📈 Practical Patterns

Example 2 — Ready Handlers Wait While Held

How It Works

Example 3 — Multiple Holds Need Matching Releases

How It Works

Example 4 — Modern $.when Replacement (Recommended)

How It Works

Example 5 — Calling holdReady After Ready Has No Effect

How It Works

🚀 Common Use Cases

🧠 How holdReady Gates the Ready Event

Early hold

DOM parses

Async work

Ready fires

📝 Notes

Browser Support

jQuery jQuery.holdReady()

Conclusion

💡 Best Practices

✅ Do

❌ Don’t

Key Takeaways

Five things to remember about jQuery.holdReady()

true/false

Early

Counter

Deprecated

$.when

❓ Frequently Asked Questions

🧩 Related jQuery Topics

jQuery.ready

.load()

jQuery.getScript()

Next: jQuery .load() Method

About the author

Understanding the `jQuery.holdReady()` Method

📋 `holdReady` vs `$.when($.ready, promise)`

Example 1 — Official `$.getScript` Plugin Demo

Example 4 — Modern `$.when` Replacement (Recommended)

Example 5 — Calling `holdReady` After Ready Has No Effect

🧠 How `holdReady` Gates the Ready Event

Five things to remember about `jQuery.holdReady()`