jQuery Deferred rejectWith() Method

What You’ll Learn

The rejectWith() method settles a Deferred as failed like reject(), but lets you set this inside fail() callbacks and pass arguments as an array. This tutorial covers syntax, five examples, comparisons with reject() and resolveWith(), and when custom context matters for error handling.

Introduction

Error handlers often need to update a specific UI widget, form view, or logging service. Inside a plain fail() callback, this may not point where you expect — especially after setTimeout, AJAX callbacks, or nested functions. rejectWith(context, args) solves that by binding this to your chosen object when the Deferred settles as rejected.

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 rejectWith() Method

rejectWith() is part of jQuery’s Deferred Object API (since jQuery 1.7). Calling deferred.rejectWith(context, args) locks the Deferred in the rejected state and invokes every fail(), catch(), and rejection branch of always() handler with this set to context and parameters taken from the args array.

Unlike reject(), which passes values directly with default this binding, rejectWith() gives you explicit control over both the callback context and how multiple arguments are delivered.

📝 Syntax

General form of deferred.rejectWith:

deferred.rejectWith( context, args )

Parameters

• context — object used as this when each fail() callback runs.
• args — array or array-like object whose values are passed as separate arguments to failure handlers (e.g. ["Network error"] or [404, "Not found", "ERR_404"]).

Return value

• Returns the same Deferred object (already settled as rejected).

Minimal example

const errorView = {
  source: "Login form",
  show: function (message) {
    console.error(this.source + ":", message);
  }
};

const dfd = $.Deferred();

dfd.fail(function (message) {
  this.show(message);
});

dfd.rejectWith(errorView, ["Invalid credentials"]);

Examples Gallery

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

const errorHandler = {
  source: "Payment API",
  report: function (message) {
    console.error(this.source + " failed:", message);
  }
};

const dfd = $.Deferred();

dfd.fail(function (message) {
  this.report(message);
});

dfd.rejectWith(errorHandler, ["Card declined"]);

Payment API failed: Card declined

const formView = {
  formId: "#signup-form",
  showErrors: function (errors) {
    console.log("Form " + this.formId + " errors:", errors.join(", "));
  }
};

const dfd = $.Deferred();

dfd.fail(function (errors) {
  this.showErrors(errors);
});

const validationErrors = ["Email is required", "Password too short"];
dfd.rejectWith(formView, [validationErrors]);

Form #signup-form errors: Email is required, Password too short

const logger = {
  tag: "AUTH",
  log: function (msg) {
    return this.tag + ": " + msg;
  }
};

const dfdPlain = $.Deferred();
dfdPlain.fail(function (msg) {
  console.log("plain reject →", typeof this.tag, msg);
});
dfdPlain.reject("Session expired");

const dfdWith = $.Deferred();
dfdWith.fail(function (msg) {
  console.log("rejectWith →", this.log(msg));
});
dfdWith.rejectWith(logger, ["Session expired"]);

plain reject → undefined Session expired
rejectWith → AUTH: Session expired

const apiClient = {
  name: "Users API",
  onHttpError: function (status, message, code) {
    console.log(this.name + ":", status, message, "(" + code + ")");
  }
};

const dfd = $.Deferred();

dfd.fail(function (status, message, code) {
  this.onHttpError(status, message, code);
});

dfd.rejectWith(apiClient, [503, "Service unavailable", "ERR_503"]);

Users API: 503 Service unavailable (ERR_503)

const uploadService = {
  label: "Photo upload",
  handleFailure: function (reason) {
    console.error(this.label + " aborted:", reason);
  }
};

const dfd = $.Deferred();

dfd.fail(function (reason) {
  this.handleFailure(reason);
});

setTimeout(function () {
  const uploadOk = false;

  if (uploadOk) {
    dfd.resolveWith(uploadService, ["Upload complete"]);
  } else {
    dfd.rejectWith(uploadService, ["Network timeout"]);
  }
}, 400);

Photo upload aborted: Network timeout

🚀 Use Cases

• Form validation — bind failure to a form view that renders field errors in the DOM.
• API error reporting — pass an HTTP client or logger as this with status codes and messages.
• Widget-level failures — let a widget object handle its own error UI when async work fails.
• Deferred chains — reject at any stage with consistent context for downstream fail() handlers.
• Consistent With-methods — use the same context for notifyWith(), resolveWith(), and rejectWith() in one workflow.

📝 Notes

• The args parameter must be array-like — use [message] even for a single argument.
• rejectWith() does not run done() — only failure and always() handlers.
• After rejection, further rejectWith() or resolveWith() calls are ignored.
• Prefer explicit context objects over bare this inside async callbacks.
• Consumers holding only a promise() cannot call rejectWith() — only the Deferred owner settles the outcome.

💡 Best Practices