jQuery Deferred then() Method

What Is then()?

deferred.then(doneFilter [, failFilter] [, progressFilter]) adds handlers for resolve, reject, and progress. Since jQuery 1.8 it returns a new Promise that can transform status and values.

dfd.then(onDone, onFail, onProgress)

// Filter resolve value
dfd.then(function (v) { return v * 2; })

// Fail only
dfd.then(null, onFail)

// Returns a NEW Promise (chainable)

How to Use then()

Attach filters, optionally transform the value, then continue the chain.

1. Start from a Deferred or jqXHR (e.g. $.get).
2. Call .then(doneFilter, failFilter) — pass null to skip a slot.
3. Return a value or another Promise from the filter to feed the next step.
4. Chain more .then() / .done() / .fail() on the returned Promise.

Pseudocode

function then(deferred, doneFilter, failFilter, progressFilter):
    promise = new Promise linked to deferred

    when deferred resolves(value):
        if doneFilter:
            next = doneFilter(value)
            settle promise from next (value or another promise)
        else:
            resolve promise with value

    // similar for reject → failFilter, notify → progressFilter
    return promise

Cheat Sheet

Keep these facts handy while chaining Deferreds.

Live Preview

Pick a scenario and see how then() filters resolve or reject.

success: ok

jQuery Examples

Short, copy-ready snippets. Open DevTools Console, or use Try It Yourself for a live editor.

var dfd = $.Deferred();

dfd.then(
  function (msg) {
    console.log("success: " + msg);
  },
  function (err) {
    console.log("error: " + err);
  }
);

dfd.resolve("ok");
// success: ok

success: ok

var defer = $.Deferred();
var filtered = defer.then(function (value) {
  return value * 2;
});

filtered.done(function (value) {
  console.log("Value is (2*5=) 10: " + value);
});

defer.resolve(5);
// Value is (2*5=) 10: 10

Value is (2*5=) 10: 10

var defer = $.Deferred();
var filtered = defer.then(null, function (value) {
  return value * 3;  // recover with a new value
});

filtered.done(function (value) {
  console.log("recovered (3*6=) 18: " + value);
});

defer.reject(6);
// recovered (3*6=) 18: 18

recovered (3*6=) 18: 18

var dfd = $.Deferred();

dfd
  .then(function (n) { return n + 1; })
  .then(function (n) { return n * 10; })
  .done(function (n) {
    console.log(n);  // 40
  });

dfd.resolve(3);
// 3 → 4 → 40

40

Performance Notes

Promise allocation is usually tiny next to network or DOM work. Choose then for clarity when values must flow; use done for simple logging/UI.

Key Takeaways