jQuery Deferred then() Method

What You’ll Learn

The then() method registers success and optional failure handlers while building a transformable promise chain. This tutorial covers syntax, five examples, comparisons with done(), fail(), and deprecated pipe(), and jQuery 3+ chaining rules.

Introduction

Real apps rarely stop at one async step. You fetch a user ID, then load a profile, then format the result. The then() method is jQuery’s primary tool for linking those steps — handling both success and failure in one call and passing transformed values forward.

Since jQuery 3.0, then() follows Promises/A+ semantics and replaces deprecated pipe(). It works on Deferreds, promises returned from promise(), and jqXHR objects from $.ajax().

Understanding the then() Method

then(onFulfilled, onRejected) registers callbacks that run when the promise settles. Unlike done() and fail(), what you return from a then() handler matters — that return value (or returned promise) becomes the input for the next link in the chain.

Each then() call returns a new promise, so you can keep chaining without mutating the original Deferred.

📝 Syntax

General form of deferred.then:

deferred.then( onFulfilled [, onRejected ] )

Parameters

• onFulfilled — runs when the promise resolves; may return a value or another promise for the chain to wait on.
• onRejected (optional) — runs when the promise rejects; can recover by returning a value or let errors propagate downstream.

Return value

• Returns a new promise representing the outcome of the handlers and any chained async work.

Success + failure handlers

function loadData() {
  const dfd = $.Deferred();
  setTimeout(function () { dfd.resolve({ items: 3 }); }, 400);
  return dfd.promise();
}

loadData().then(
  function (data) {
    console.log("Success:", data.items, "items");
  },
  function (err) {
    console.error("Failed:", err);
  }
);

Examples Gallery

Each example shows a common then() pattern with runnable Deferred code — no fake URLs required. Use the Try-it links to experiment interactively.

function request(ok) {
  const dfd = $.Deferred();
  setTimeout(function () {
    if (ok) {
      dfd.resolve({ message: "Data received" });
    } else {
      dfd.reject("Request failed");
    }
  }, 400);
  return dfd.promise();
}

request(true).then(
  function (data) {
    console.log("OK:", data.message);
  },
  function (err) {
    console.error("ERR:", err);
  }
);

OK: Data received

const dfd = $.Deferred();
dfd.resolve(5);

dfd.then(function (n) {
  return n * 10;
}).then(function (doubled) {
  console.log(doubled);  // 50
});

50

function fetchUserId() {
  const d = $.Deferred();
  setTimeout(function () { d.resolve({ id: 42 }); }, 300);
  return d.promise();
}

function fetchProfile(userId) {
  const d = $.Deferred();
  setTimeout(function () {
    d.resolve({ userId: userId, name: "Alex" });
  }, 300);
  return d.promise();
}

fetchUserId()
  .then(function (data) {
    return fetchProfile(data.id);
  })
  .then(function (profile) {
    console.log(profile.name);  // Alex
  });

Alex

const dfd = $.Deferred();
dfd.reject("Network timeout");

dfd.then(null, function (reason) {
  return "Recovered: " + reason;
}).then(function (message) {
  console.log(message);
});

Recovered: Network timeout

const dfdA = $.Deferred().resolve(3);
const dfdB = $.Deferred().resolve(3);

dfdA.done(function (n) {
  return n + 7;  // return ignored
}).done(function (n) {
  console.log("done chain:", n);  // 3
});

dfdB.then(function (n) {
  return n + 7;
}).then(function (n) {
  console.log("then chain:", n);  // 10
});

done chain: 3
then chain: 10

🚀 Use Cases

• Chained AJAX — load a resource, transform the response, then fetch related data.
• Data pipelines — parse JSON, validate, enrich, and render through sequential then() steps.
• Unified error handling — attach onRejected or trailing catch() for a whole chain.
• Migrating from pipe() — replace deprecated filters with then(onFulfilled, onRejected).
• Parallel tasks — combine multiple promises with $.when(), then process results in one then().

📝 Notes

• Since jQuery 3.0, then() is Promises/A+ compatible — prefer it over pipe().
• Returning nothing (undefined) passes undefined to the next handler.
• Thrown errors inside then() reject the returned promise automatically.
• then() handlers on an already-settled promise may run asynchronously (microtask) in jQuery 3+.
• For simple logging after AJAX, .done() / .fail() remain readable — use then() when transforming.

💡 Best Practices