What Is the jQuery $.holdReady() Method Used For?

The $.holdReady() method in jQuery is used to delay or pause the execution of jQuery's ready event until specific external dependencies have finished loading. This article explains how $.holdReady() functions, why developers use it, how to implement it correctly, and its status in modern versions of jQuery.

Purpose of $.holdReady()

Normally, jQuery executes any handler attached to $(document).ready() as soon as the Document Object Model (DOM) is fully loaded. However, some web applications require additional resources—such as external JavaScript libraries, internationalization files, or dynamic plugins—to load before any DOM-dependent code runs.

The $.holdReady() method allows you to delay the execution of the ready event until your conditions are satisfied, ensuring that your scripts do not fail due to missing dependencies.

How It Works

The method accepts a single boolean parameter:

  • $.holdReady(true): Places a hold on the ready event, preventing it from executing even if the DOM is already fully loaded.
  • $.holdReady(false): Releases the hold. Once all active holds are released and the DOM is ready, the ready handlers execute immediately.

You can call $.holdReady(true) multiple times for different resources. Each hold must be countered with a corresponding $.holdReady(false) before jQuery will execute the ready handlers.

Syntax and Implementation

$.holdReady(true) must be called before the ready event has fired, typically placed as early as possible in the <head> of the HTML document.

// Hold the ready event
$.holdReady(true);

// Dynamically load an external script or plugin
$.getScript("https://example.com/plugin.js", function() {
  // Release the hold once the script is loaded
  $.holdReady(false);
});

// This will only run after both the DOM is ready AND the plugin is loaded
$(document).ready(function() {
  console.log("DOM is ready and external plugin is loaded.");
});

Deprecation Status

In modern web development, $.holdReady() is rarely needed. It was officially deprecated in jQuery 3.2.0 and removed in jQuery 4.0.0.

Modern development practices achieve the same outcome using native JavaScript capabilities:

  • Native ES modules (<script type="module">), which defer execution by default.
  • The defer and async attributes on standard <script> tags.
  • Native JavaScript Promises and async/await patterns to manage asynchronous script dependencies.