jQuery Deferred promise() Method

Beginner
7 min read
Updated: Oct 2026
5 examples
Live preview
jQuery deferred.promise() — return a read-only Promise from a Deferred
Definition

What Is promise()?

deferred.promise() returns a Promise for that Deferred (since jQuery 1.5). The Promise lets other code attach handlers or read state(), but it hides methods that change the outcome — resolve, reject, notify, and their *With forms.

Remember
deferred.promise([target])

Promise has:  then, done, fail, always, progress, state, pipe, promise
Promise lacks: resolve, reject, notify (+ *With)

Pattern:
  keep Deferred private
  return dfd.promise() to callers
NeedUse
Expose listeners onlyreturn dfd.promise()
Settle the workKeep the Deferred; call resolve() / reject()
Promote an objectdfd.promise(existingObj)
Approach

How to Use promise()

Own the Deferred; hand out a Promise.

  1. Create a Deferred inside your async function.
  2. Start the work; call resolve / reject / notify only there.
  3. Return dfd.promise() (or dfd.promise(target)).
  4. Callers attach then, done, fail, or progress — they cannot settle it.
PieceRequired?Role
targetOptionalObject that receives promise methods; returned instead of a new Promise
Return—Promise (or the target with promise methods attached)
Since—jQuery 1.5

Pseudocode

Pseudocode
function asyncWork():
    dfd = Deferred()
    start timers / AJAX / tasks
    on success: dfd.resolve(value)
    on failure: dfd.reject(reason)
    return dfd.promise()   // callers listen only

caller:
    asyncWork().done(onOk).fail(onErr)
    // asyncWork().resolve(...)  → not available
Reference

Cheat Sheet

Keep these facts handy when wrapping async APIs.

TopicDetail
Syntaxdeferred.promise([target])
Listenersthen, done, fail, always, progress
Inspectstate(), promise()
Hiddenresolve, reject, notify (+ *With)
targetAttach methods onto an existing object
vs DeferredSame outcome; Promise cannot settle it
SincejQuery 1.5
Try it

Live Preview

Compare a full Deferred with the Promise from promise().

Browser demo of deferred.promise — same idea as the examples below.

Result
Deferred has resolve: true
Promise has resolve: false
Promise has done: true

/* promise() hides settling methods */
Code

jQuery Examples

Short, copy-ready snippets. Open the browser console, or use Try It Yourself for a live editor.

Example 1 — Return promise() from a Helper

Create a Deferred inside the function; give callers only the Promise.

jQuery
function fetchData() {
  var dfd = $.Deferred();
  setTimeout(function () {
    dfd.resolve({ data: "Sample data" });
  }, 200);
  return dfd.promise();
}

fetchData().done(function (response) {
  console.log(response.data);  // Sample data
});
Try It Yourself

How It Works

  1. Private Deferred. dfd lives only inside fetchData.
  2. Resolve later. The timeout settles success with an object.
  3. Return Promise. Callers get promise(), not dfd.
  4. Listen with done. When resolved, response.data is logged.

Example 2 — Promise Hides resolve

Compare methods on the Deferred versus the Promise.

jQuery
var dfd = $.Deferred();
var p = dfd.promise();

console.log(typeof dfd.resolve);  // "function"
console.log(typeof p.resolve);    // "undefined"
console.log(typeof p.done);       // "function"
Try It Yourself

How It Works

  1. Full Deferred. dfd.resolve exists so the owner can settle.
  2. Promise view. p.resolve is missing — callers cannot force success.
  3. Listeners remain. p.done is still a function.
  4. Same outcome. When dfd resolves, handlers on p still run.

Example 3 — done and fail on the Promise

Attach success and failure handlers to the returned Promise.

jQuery
function loadUser(ok) {
  var dfd = $.Deferred();
  setTimeout(function () {
    if (ok) dfd.resolve("Alex");
    else dfd.reject("offline");
  }, 200);
  return dfd.promise();
}

loadUser(true).done(function (name) {
  console.log("Hi", name);   // Hi Alex
}).fail(function (err) {
  console.log("Err", err);
});
Try It Yourself

How It Works

  1. Helper owns settle. ok chooses resolve or reject inside the timeout.
  2. Return Promise. The caller never sees dfd.
  3. Chain done/fail. Success prints Hi Alex.
  4. Try fail. Call loadUser(false) to exercise the fail path.

Example 4 — promise(target)

Attach promise methods onto an existing object (official target pattern).

jQuery
var obj = {
  hello: function (name) {
    console.log("Hello " + name);
  }
};

var defer = $.Deferred();
defer.promise(obj);

defer.resolve("John");

obj.done(function (name) {
  obj.hello(name);  // Hello John
});
Try It Yourself

How It Works

  1. Start with an object. obj already has hello.
  2. Promote it. defer.promise(obj) copies promise methods onto obj.
  3. Resolve the Deferred. The owner still settles via defer.
  4. Use obj as a Promise. obj.done runs and calls hello("John").

Example 5 — Read state() on the Promise

Inspect pending vs resolved without exposing settle methods.

jQuery
var dfd = $.Deferred();
var p = dfd.promise();

console.log(p.state());  // pending
dfd.resolve("ok");
console.log(p.state());  // resolved
Try It Yourself

How It Works

  1. Create views. p observes the same Deferred as dfd.
  2. Before settle. p.state() is "pending".
  3. Owner resolves. Only dfd can call resolve.
  4. After settle. p.state() becomes "resolved".

Edge Cases & Pitfalls

Check these before returning Deferreds from public APIs.

leak

Do not return the Deferred

Returning dfd lets callers call resolve/reject/notify. Always return dfd.promise() from public helpers.

target

promise(target) mutates the object

Methods are attached onto target. Avoid accidental name clashes with existing properties like done or state.

pipe

pipe is still on the Promise

The Promise exposes deprecated pipe(). Prefer then() in new code.

native

Not identical to native Promise

jQuery Promises add done/fail/progress. jQuery 3+ then is Promises/A+-compatible, but the full API still differs from new Promise.

Compatibility

Browser Support

deferred.promise() needs jQuery 1.5+ loaded. It works across jQuery 1.5–3.x as the standard way to expose a read-only Deferred view.

✓ jQuery 1.5+

deferred.promise()

Works in Chrome, Firefox, Safari, and Edge when jQuery 1.5+ is loaded. Use it whenever you return async handles from helpers.

100% With jQuery 1.5+
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
promise() Universal

Bottom line: Safe for all jQuery versions that include Deferreds. Prefer returning promise() from every public async API.

Analysis

Performance Notes

ApproachCostBest for
dfd.promise()Tiny wrapperPublic async APIs
Return raw dfdSame runtime, worse safetyAvoid in shared code
promise(target)Copies methods onto objectWidget / API objects that should be thenable

The cost of promise() is negligible next to timers or network work. Use it for API safety, not micro-optimization.

Remember

Key Takeaways

  • Role: expose a read-only view of a Deferred.
  • Pattern: keep Deferred private; return promise().
  • Hidden: no resolve / reject / notify on the Promise.
  • target: promise(obj) makes an existing object thenable.

One line: return deferred.promise() so callers can listen, not settle.

Frequently Asked Questions

promise() returns a Promise tied to the same outcome as the Deferred. Callers can use then, done, fail, always, progress, state, pipe, and promise — but not resolve, reject, notify, or the *With variants.
Encapsulation. Only the owner should settle the operation. Returning promise() lets other code attach handlers or inspect state without forcing resolve, reject, or notify.
promise(target) attaches promise methods onto an existing object and returns that object. Useful when an API object should also act as a thenable Promise.
No. The Promise does not expose resolve, reject, or notify. Only the original Deferred can settle the work.
Similar idea — a future result — but jQuery’s Promise also supports done/fail/progress. In jQuery 3+, then() follows Promises/A+ semantics.
No. Each promise() view observes the same Deferred. Settling the Deferred once settles every promise derived from it.

Next: deferred.reject()

Learn how the Deferred owner marks a Promise as failed.

reject() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

9 people found this page helpful

jQuery deferred.progress() Method jQuery deferred.reject() Method