jQuery Deferred notifyWith() Method

What You’ll Learn

The notifyWith() method sends progress updates like notify(), but lets you set this inside progress() callbacks and pass arguments as an array. This tutorial covers syntax, five examples, comparisons with notify() and resolveWith(), and when custom context matters.

Introduction

Progress handlers often need to update a specific UI widget or view model. Inside a plain progress() callback, this may not point where you expect — especially after setTimeout or nested functions. notifyWith(context, args) solves that by binding this to your chosen object for each progress notification.

It mirrors the With family: resolveWith() for success, rejectWith() for failure, and notifyWith() for interim progress — all with the same context-and-array pattern.

Understanding the notifyWith() Method

notifyWith() is part of jQuery’s Deferred Object API (since jQuery 1.7). Calling deferred.notifyWith(context, args) invokes every progress() handler with this set to context and parameters taken from the args array.

The Deferred stays pending — just like notify(). When work completes, call resolve(), resolveWith(), or the matching reject method to settle the final outcome.

📝 Syntax

General form of deferred.notifyWith:

deferred.notifyWith( context, args )

Parameters

• context — object used as this when each progress() callback runs.
• args — array or array-like object whose values are passed as separate arguments to progress handlers (e.g. [50] or [2, 5, "Saving"]).

Return value

• Returns the same Deferred object for chaining further progress or settlement calls.

Minimal example

const view = {
  label: "Import",
  report: function (pct) {
    console.log(this.label + ":", pct + "%");
  }
};

const dfd = $.Deferred();

dfd.progress(function (pct) {
  this.report(pct);
});

dfd.notifyWith(view, [40]);
dfd.resolve();

Examples Gallery

Each example shows how notifyWith() binds this for progress handlers. Use the Try-it links to run them interactively.

const view = {
  label: "Import job",
  report: function (pct) {
    console.log(this.label + " → " + pct + "%");
  }
};

const dfd = $.Deferred();

dfd.progress(function (pct) {
  this.report(pct);
});

dfd.notifyWith(view, [25]);
dfd.notifyWith(view, [100]);
dfd.resolve();

Import job → 25%
Import job → 100%

const barWidget = {
  selector: "#upload-bar",
  setPercent: function (pct) {
    $(this.selector).css("width", pct + "%");
    console.log("Bar width:", pct + "%");
  }
};

const dfd = $.Deferred();

dfd.progress(function (pct) {
  this.setPercent(pct);
});

dfd.notifyWith(barWidget, [30]);
dfd.notifyWith(barWidget, [70]);
dfd.notifyWith(barWidget, [100]);
dfd.resolve();

Bar width: 30%
Bar width: 70%
Bar width: 100%

const panel = { title: "Upload panel" };
const dfd = $.Deferred();

dfd.progress(function () {
  // notify() — this is NOT panel (often window in browsers)
  console.log("notify() this.title:", this.title);
});

dfd.notify(50);

dfd.progress(function () {
  // notifyWith() — this IS panel
  console.log("notifyWith() this.title:", this.title);
});

dfd.notifyWith(panel, [100]);
dfd.resolve();

notify() this.title: undefined
notifyWith() this.title: Upload panel

const wizard = {
  name: "Setup wizard",
  onStep: function (current, total, label) {
    console.log(this.name + " — Step " + current + "/" + total + ": " + label);
  }
};

const dfd = $.Deferred();

dfd.progress(function (current, total, label) {
  this.onStep(current, total, label);
});

dfd.notifyWith(wizard, [1, 3, "Account"]);
dfd.notifyWith(wizard, [2, 3, "Preferences"]);
dfd.notifyWith(wizard, [3, 3, "Review"]);
dfd.resolve();

Setup wizard — Step 1/3: Account
Setup wizard — Step 2/3: Preferences
Setup wizard — Step 3/3: Review

const task = {
  title: "Background sync",
  onProgress: function (value) {
    console.log(this.title + " → " + value + "%");
  }
};

const dfd = $.Deferred();
const steps = [20, 40, 60, 80, 100];

dfd.progress(function (value) {
  this.onProgress(value);
});

steps.forEach(function (pct, index) {
  setTimeout(function () {
    dfd.notifyWith(task, [pct]);
    if (pct === 100) {
      dfd.resolveWith(task, ["Sync complete"]);
    }
  }, 300 * (index + 1));
});

Background sync → 20%
Background sync → 40%
Background sync → 60%
Background sync → 80%
Background sync → 100%
(done receives: Sync complete)

🚀 Use Cases

• File upload widgets — bind progress to an uploader instance that owns the progress bar element.
• Multi-step wizards — pass step metadata with a wizard controller as this.
• Background sync tasks — report percent complete from timers or workers without losing object context.
• Form submission flows — update validation or save status on a form view model during server round-trips.
• Consistent With-methods — use the same context for notifyWith(), resolveWith(), and rejectWith() in one workflow.

📝 Notes

• The args parameter must be array-like — use [value] even for a single argument.
• notifyWith() does not run done() or fail() — only progress() handlers.
• After resolve or reject, further notifyWith() calls are ignored.
• Prefer explicit context objects over bare this inside async callbacks.
• Consumers holding only a promise() cannot call notifyWith() — only the Deferred owner emits progress.

💡 Best Practices