jQuery Deferred progress() Method

What You’ll Learn

The progress() method registers callbacks that run when notify() sends interim updates. Use it for progress bars, step labels, and status text while a Deferred is still pending — then handle the final result with done() or fail().

Introduction

Success and failure callbacks tell users how a task ended — but long operations also need mid-flight feedback. jQuery’s progress() method listens for notify() pings: percentage complete, current step, or any status message emitted while the Deferred remains pending.

Think of the trio as a complete async story: progress() for updates, done() for success, fail() for errors.

Understanding the progress() Method

progress() is part of jQuery’s Deferred Object API (since jQuery 1.7). Calling deferred.progress(callback) adds your function to a progress queue. Each time the Deferred owner calls notify() or notifyWith(), jQuery invokes every progress handler with the notify arguments.

Progress handlers do not change Deferred state. The operation stays pending until resolve() or reject() runs — only then do done() or fail() fire.

📝 Syntax

General form of deferred.progress:

deferred.progress( progressCallback [, progressCallback ] )

Parameters

• progressCallback — function executed on each notify() call. Receives whatever arguments were passed to notify() or notifyWith().

Return value

• Returns the same Deferred object for chaining done(), fail(), or another progress().

Full progress + completion flow

const dfd = $.Deferred();

dfd.progress(function (message) {
  console.log("Progress:", message);
});

dfd.done(function (result) {
  console.log("Done:", result);
});

dfd.notify("50% complete");
dfd.notify("90% complete");
dfd.resolve("Operation completed successfully");

Examples Gallery

Each example shows how progress() receives notify() updates. Use the Try-it links to run them interactively.

const dfd = $.Deferred();

dfd.progress(function (message) {
  console.log("Progress:", message);
});

dfd.done(function (result) {
  console.log("Done:", result);
});

dfd.notify("50% complete");
dfd.notify("90% complete");
dfd.resolve("Operation completed successfully");

Progress: 50% complete
Progress: 90% complete
Done: Operation completed successfully

const dfd = $.Deferred();

dfd.progress(function (percent) {
  $("#upload-bar").css("width", percent + "%");
  console.log("Upload:", percent + "%");
});

dfd.done(function () {
  console.log("Upload finished");
});

[25, 50, 75, 100].forEach(function (pct) {
  dfd.notify(pct);
});

dfd.resolve({ file: "photo.jpg" });

Upload: 25%
Upload: 50%
Upload: 75%
Upload: 100%
Upload finished

const dfd = $.Deferred();

dfd.progress(function (step) {
  console.log("Log step:", step);
});

dfd.progress(function (step) {
  $("#status").text("Step " + step + " of 3");
});

dfd.notify(1);
dfd.notify(2);
dfd.notify(3);
dfd.resolve("All steps done");

Log step: 1
Log step: 2
Log step: 3
(UI shows Step 3 of 3)

function runTask(shouldFail) {
  const dfd = $.Deferred();

  dfd.progress(function (pct) {
    console.log("Working:", pct + "%");
  });

  dfd.done(function (msg) {
    console.log("Success:", msg);
  });

  dfd.fail(function (err) {
    console.log("Failed:", err);
  });

  dfd.notify(50);

  if (shouldFail) {
    dfd.reject("Validation error");
  } else {
    dfd.notify(100);
    dfd.resolve("Saved");
  }

  return dfd;
}

Working: 50%
Working: 100%
Success: Saved

(fail path shows Working: 50% then Failed: Validation error)

const dfd = $.Deferred();

dfd.progress(function (message) {
  console.log("Progress:", message);
});

dfd.done(function (result) {
  console.log("Done:", result);
});

setTimeout(function () {
  dfd.notify("50% complete");
}, 400);

setTimeout(function () {
  dfd.notify("90% complete");
}, 900);

setTimeout(function () {
  dfd.resolve("Operation completed successfully");
}, 1400);

Progress: 50% complete
Progress: 90% complete
Done: Operation completed successfully

🚀 Use Cases

• File uploads — update a progress bar as bytes are sent.
• Multi-step wizards — show “Step 2 of 5” as each stage completes.
• Data imports — log row counts or batch numbers during processing.
• Long computations — report iteration progress without blocking the UI thread.
• Loading indicators — swap spinner text from “Loading…” to specific status messages.

📝 Notes

• progress() only runs when notify() or notifyWith() is called — it does not fire on resolve or reject alone.
• Register handlers before the first notify for predictable behavior.
• Put final success logic in done(), not progress().
• Consumers with only a promise() view can attach progress() but cannot call notify().
• Native Promises have no progress() — this is jQuery-specific.

💡 Best Practices