jQuery $.Deferred() Method

What You’ll Learn

$.Deferred() is the factory that creates jQuery Deferred objects — the building blocks behind $.ajax() callbacks, custom async helpers, and promise-style chains. This tutorial covers creation, resolve/reject, returning promise(), and five hands-on examples.

Introduction

Asynchronous programming keeps web pages responsive while network calls, timers, and animations run in the background. jQuery has supported this pattern since version 1.5 with Deferred objects — and $.Deferred() is how you create them.

Think of a Deferred as a ticket for work that will finish later. You hand the ticket to callers so they can register done() and fail() handlers; when your async task completes, you call resolve() or reject() to settle the ticket.

Understanding the $.Deferred() Method

$.Deferred() (identical to jQuery.Deferred()) is a constructor-style factory — not a method on an existing Deferred. Each call returns a fresh Deferred object representing one async operation with three possible states:

• pending — work still running; callbacks are queued.
• resolved — success; done() and always() handlers run.
• rejected — failure; fail(), catch(), and always() handlers run.

Once resolved or rejected, the state is frozen — calling resolve() again has no effect. That guarantee makes Deferred objects predictable in chained workflows.

📝 Syntax

General forms of the Deferred factory:

jQuery.Deferred( [ beforeStart ] )

// Common alias:
const dfd = $.Deferred();

Parameters

• beforeStart (optional) — function invoked immediately with the new Deferred as this. Use it to start async setup in one place.

Return value

• A new Deferred object with methods such as resolve, reject, done, fail, always, then, and promise.

Minimal resolve example

const deferred = $.Deferred();

// …perform async work…

deferred.resolve(result);  // settle as success

Examples Gallery

Each example creates a Deferred from scratch. Use DevTools or the Try-it links with jQuery 3.7+ loaded from the CDN.

const dfd = $.Deferred();

dfd.done(function (value) {
  console.log("done:", value);
});

dfd.resolve("Hello from Deferred");

done: Hello from Deferred

const dfd = $.Deferred();

dfd.fail(function (reason) {
  console.error("fail:", reason);
});

dfd.reject("Validation failed");

fail: Validation failed

function loadConfig() {
  const dfd = $.Deferred();

  setTimeout(function () {
    dfd.resolve({ theme: "dark", lang: "en" });
  }, 500);

  return dfd.promise();  // callers cannot call resolve()
}

loadConfig().done(function (cfg) {
  console.log(cfg.theme, cfg.lang);
});

dark en

function fetchTotal() {
  const dfd = $.Deferred();

  setTimeout(function () {
    if (Math.random() > 0.3) {
      dfd.resolve(42);
    } else {
      dfd.reject("Service down");
    }
  }, 700);

  return dfd.promise();
}

fetchTotal()
  .done(function (n) { console.log("Total:", n); })
  .fail(function (err) { console.error(err); });

Total: 42
— or —
Service down

const dfd = $.Deferred(function (deferred) {
  deferred.notify("working…");

  setTimeout(function () {
    deferred.resolve("task complete");
  }, 400);
});

dfd.progress(function (msg) {
  console.log("progress:", msg);
});

dfd.done(function (result) {
  console.log("done:", result);
});

progress: working…
done: task complete

🚀 Use Cases

• AJAX wrappers — unify success and error callbacks before fetch was standard.
• Animation coordination — resolve a Deferred when a .fadeOut() animation completes.
• Parallel tasks — combine multiple Deferreds with $.when() (covered on the Deferred hub).
• Timeouts — reject if work exceeds a deadline using setTimeout plus reject().
• Plugin APIs — return promise() from jQuery plugins so callers chain done() naturally.

📝 Notes

• $.Deferred() and jQuery.Deferred() are the same function.
• Resolve or reject exactly once; subsequent calls are ignored.
• Handlers registered after settlement still run immediately (if they match the state).
• Prefer returning promise() from public APIs to hide resolve/reject.
• Modern greenfield apps often use native Promise, but jQuery Deferred remains useful in legacy codebases.

💡 Best Practices