jQuery Deferred

What You’ll Learn

Asynchronous code runs in the background — AJAX calls, timers, animations. jQuery Deferred gives you a structured way to run code when those tasks succeed, fail, or update progress. This hub links to 18 Deferred method tutorials.

Introduction

When a task takes time — fetching data, waiting for an animation, reading a file — you cannot block the browser. Instead, you register callbacks that run later. jQuery Deferred is the utility that queues those callbacks and fires them when you call resolve() or reject().

What Is jQuery Deferred?

A Deferred object represents the eventual outcome of an asynchronous operation. It can be pending (still running), resolved (success), or rejected (failure). You attach handlers before settlement, and jQuery runs them in order when the state changes.

Key Features

• Callback attachment — Register multiple handlers for success, failure, progress, or either outcome.
• Promise integration — Expose a read-only promise() so callers cannot accidentally resolve your task.
• Chaining — Use then() to pipe results through a pipeline, similar to native Promises.
• AJAX built-in — $.ajax() returns a jqXHR that already behaves like a Deferred.

📝 Syntax

Create a Deferred, attach handlers, and settle it:

const dfd = $.Deferred();

dfd.done(function (data) {
  console.log("Success:", data);
}).fail(function (err) {
  console.error("Failed:", err);
}).always(function () {
  console.log("Cleanup runs either way");
});

// Later, when async work finishes:
dfd.resolve("Hello from Deferred");

Method groups

When to Use Deferred

• Custom async APIs — Wrap setTimeout, third-party SDKs, or Web APIs in a Deferred your app can consume uniformly.
• AJAX requests — Chain .done() / .fail() on $.ajax() without nested callbacks.
• Animation sequences — Coordinate code that runs when effects complete or fail.
• Module boundaries — Return promise() from a module so internals stay private.
• Progress UI — Use notify() and progress() for upload bars or multi-step wizards.

Examples Gallery

Include jQuery 3.7+ and open DevTools Console (F12) to run each snippet.

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

  setTimeout(function () {
    dfd.resolve("Hello, Deferred!");
  }, 500);

  return dfd.promise();
}

fetchGreeting().done(function (msg) {
  console.log(msg);
});

Hello, Deferred!

function loadData(shouldFail) {
  const dfd = $.Deferred();
  setTimeout(function () {
    if (shouldFail) {
      dfd.reject("Network error");
    } else {
      dfd.resolve({ id: 1, name: "Ada" });
    }
  }, 300);
  return dfd.promise();
}

loadData(false)
  .done(function (data) { console.log("Loaded:", data.name); })
  .fail(function (err) { console.error(err); })
  .always(function () { console.log("Request finished"); });

Loaded: Ada
Request finished

$.Deferred()
  .resolve(10)
  .then(function (n) { return n * 2; })
  .then(function (n) { return "Result: " + n; })
  .done(function (msg) { console.log(msg); });

Result: 20

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

  setTimeout(function () {
    dfd.resolve("Timer done");
  }, 400);

  // Public API — no resolve/reject exposed
  return {
    onComplete: dfd.promise()
  };
})();

Timer.onComplete.done(function (msg) {
  console.log(msg);
});

// Timer.onComplete.resolve("hack"); // undefined — safe!

Timer done

const dfd = $.Deferred();

console.log("Before:", dfd.state()); // pending

dfd.resolve("OK");
console.log("After resolve:", dfd.state()); // resolved

const dfd2 = $.Deferred();
dfd2.reject("Oops");
console.log("After reject:", dfd2.state()); // rejected

Before: pending
After resolve: resolved
After reject: rejected

🚀 Use Cases

• AJAX requests — Handle server responses and errors without deeply nested callbacks.
• Animation sequences — Run the next step when .fadeOut() or custom effects complete.
• Complex workflows — Coordinate tasks that depend on other async operations finishing first.
• Plugin APIs — Let plugin users attach callbacks while you control when work completes.

🌟 Advantages

• Cleaner organization — Separate success, failure, and cleanup instead of one giant callback.
• Better error handling — Route failures to fail() or catch() consistently.
• Promise compatibility — Integrates with jQuery AJAX and patterns familiar from native Promises.
• Progress support — Report interim status with notify() — something basic callbacks lack.

💬 Usage Tips

• Register handlers first — Attach done / fail before calling resolve or handlers may miss synchronous settlement.
• Return promise() — From public functions, not the raw Deferred.
• Prefer state() — Over deprecated status helpers in new code.
• Use then() for pipelines — Replace deprecated pipe() in jQuery 3+ projects.
• Search this index — Jump to any of 18 method pages above.

⚠️ Common Pitfalls

• Double settlement — Only the first resolve or reject counts; later calls are ignored silently.
• Leaking the Deferred — Returning the Deferred lets callers resolve your task — use promise().
• Mixing paradigms — Native Promises and jQuery Deferred are similar but not identical; test mixed chains carefully.
• Deprecated pipe() — Still documented for legacy code; choose then() for new tutorials and projects.
• Forgetting always() — UI cleanup belongs in always(), not duplicated in both done and fail.

💡 Best Practices