jQuery Deferred promise() Method

What You’ll Learn

The promise() method returns a read-only view of a jQuery Deferred. Consumers can listen with then(), done(), or catch() — but cannot call resolve() or reject(). This tutorial covers syntax, encapsulation patterns, five examples, and comparisons with full Deferred objects.

Introduction

When you build an async helper — fetch user data, run a animation sequence, wrap a timer — you usually create a $.Deferred() internally. But returning the raw Deferred gives callers the power to call resolve() or reject() themselves, which breaks encapsulation.

promise() solves that. Return deferred.promise() instead: outsiders get a thenable they can observe, while only your module settles the real Deferred.

Understanding the promise() Method

promise() creates (or augments) a promise object linked to the same underlying state as the Deferred. It exposes listener methods — done, fail, always, then, catch, progress, and state — but omits settlement methods like resolve, reject, and notify.

This is the same pattern $.ajax() uses: the jqXHR object you chain .done() onto is promise-like, while jQuery internally controls when the request completes.

📝 Syntax

General form of deferred.promise:

deferred.promise( [ target ] )

Parameters

• target (optional) — object onto which promise methods are copied. If omitted, jQuery returns a new plain object with those methods.

Return value

• A promise object (or the target object) that reflects the Deferred’s state but cannot change it.

Typical async function pattern

function fetchData() {
  const deferred = $.Deferred();

  setTimeout(function () {
    deferred.resolve({ data: "Sample data" });
  }, 500);

  return deferred.promise();
}

fetchData().then(function (response) {
  console.log("Data fetched:", response.data);
}).catch(function (error) {
  console.error("Error:", error);
});

Examples Gallery

Each example shows how promise() exposes async results safely. Use the Try-it links to run them interactively.

function fetchData() {
  const deferred = $.Deferred();

  setTimeout(function () {
    deferred.resolve({ data: "Sample data" });
  }, 500);

  return deferred.promise();
}

const promise = fetchData();

promise.then(function (response) {
  console.log("Data fetched:", response.data);
});

Data fetched: Sample data

const dfd = $.Deferred();
const promise = dfd.promise();

console.log(typeof promise.done);     // "function"
console.log(typeof promise.resolve);  // "undefined"

dfd.resolve("Settled internally");
promise.done(function (value) {
  console.log("Got:", value);
});

function
undefined
Got: Settled internally

const dfd = $.Deferred();

const loader = {
  label: "DataLoader",
  start: function () {
    setTimeout(function () {
      dfd.resolve({ items: [1, 2, 3] });
    }, 400);
    return dfd.promise(this);
  }
};

loader.start().done(function (result) {
  console.log(loader.label + ":", result.items.length, "items");
});

DataLoader: 3 items

function loadConfig() {
  const dfd = $.Deferred();
  setTimeout(function () {
    dfd.resolve({ theme: "dark", lang: "en" });
  }, 300);
  return dfd.promise();
}

const configPromise = loadConfig();

configPromise.done(function (cfg) {
  console.log("UI theme:", cfg.theme);
});

configPromise.done(function (cfg) {
  console.log("Locale:", cfg.lang);
});

UI theme: dark
Locale: en

function fetchData(fail) {
  const deferred = $.Deferred();

  setTimeout(function () {
    if (fail) {
      deferred.reject("Network error");
    } else {
      deferred.resolve({ data: "OK" });
    }
  }, 400);

  return deferred.promise();
}

fetchData(true).then(function (r) {
  console.log(r.data);
}).catch(function (err) {
  console.error("Error fetching data:", err);
});

Error fetching data: Network error

🚀 Use Cases

• Public async APIs — return promise() from module functions so callers cannot force settlement.
• AJAX wrappers — mirror $.ajax() by exposing jqXHR-style promise objects.
• Plugin interfaces — use promise(target) on a plugin instance for chainable async methods.
• Shared resources — pass one promise to multiple components waiting on the same load.
• Animation helpers — wrap .fadeOut() or custom timers and return a promise for sequencing.

📝 Notes

• Always return promise() from public APIs — keep the Deferred variable private.
• Calling promise() multiple times on the same Deferred returns equivalent thenables tied to the same state.
• jQuery 3+ promises support then() / catch() like native Promises.
• promise() does not clone async work — it only restricts the interface.
• For combining multiple promises, use $.when() with promise objects.

💡 Best Practices