jQuery Deferred isRejected() Method

What You’ll Learn

The isRejected() method returns true when a jQuery Deferred has failed — and false while it is still pending or after a successful resolve. This tutorial covers syntax, return values, five examples, comparisons with state(), and when not to poll this method.

Introduction

Callbacks like fail() react when a Deferred rejects. Sometimes you need a quick synchronous answer: has this task already failed? isRejected() answers that question with a boolean — no callback registration required.

Use it for conditional debugging, branching in test helpers, or inspecting Deferred state at a known checkpoint. For production error handling, prefer fail() or catch() — they fire automatically when rejection happens, without polling.

Understanding the isRejected() Method

isRejected() is a state query on jQuery’s Deferred object. It returns true only when the Deferred has entered the rejected state via reject(), a failed AJAX call, or a rejected promise in a chain.

It returns false when the Deferred is still pending (work not finished) or resolved (success). A Deferred can only settle once — it never flips from rejected back to resolved.

📝 Syntax

General form of deferred.isRejected:

deferred.isRejected()

Return value

• true — the Deferred has been rejected (failed).
• false — the Deferred is still pending or was resolved successfully.

Modern alternative (jQuery 3+)

if (dfd.state() === "rejected") {
  console.log("The operation failed");
}

Examples Gallery

Each example shows when isRejected() returns true or false. Use the Try-it links to run them interactively.

const dfd = $.Deferred();

dfd.reject("Network error");

console.log(dfd.isRejected());  // true
console.log(dfd.state());       // "rejected"

true
"rejected"

const dfd = $.Deferred();

console.log(dfd.isRejected());  // false
console.log(dfd.state());       // "pending"

false
"pending"

const dfd = $.Deferred();

dfd.resolve("OK");

console.log(dfd.isRejected());  // false
console.log(dfd.isResolved());  // true
console.log(dfd.state());       // "resolved"

false
true
"resolved"

const dfd = $.Deferred();

console.log("before timeout:", dfd.isRejected());  // false

setTimeout(function () {
  dfd.reject("Operation timed out");
}, 800);

dfd.fail(function () {
  console.log("in fail():", dfd.isRejected());  // true
  console.log("state():", dfd.state());         // "rejected"
});

before timeout: false
in fail(): true
state(): "rejected"

function logStatus(dfd) {
  console.log("state():", dfd.state());
  console.log("isRejected():", dfd.isRejected());
  console.log('state === "rejected":', dfd.state() === "rejected");
}

const failed = $.Deferred().reject("error");
logStatus(failed);

const ok = $.Deferred().resolve("done");
logStatus(ok);

state(): rejected
isRejected(): true
state === "rejected": true

(rejected dfd — resolved dfd shows isRejected: false)

🚀 Use Cases

• Error state detection — confirm a Deferred failed before running recovery logic.
• Conditional branching — choose different code paths in tests or debug utilities based on rejection.
• Dynamic UI updates — show error panels when state() is "rejected" after async UI loads.
• Logging — record rejection status alongside other Deferred metadata during diagnostics.
• Multi-task coordination — inspect individual Deferreds returned from $.when() after a batch completes.

📝 Notes

• isRejected() is deprecated in jQuery 3.0+ — use state() === "rejected" in new code.
• Never assume false means success — it can also mean still pending.
• Prefer fail() over polling isRejected() in production error handling.
• isRejected() and isResolved() are never both true on the same Deferred.
• For jqXHR from $.ajax(), the same state rules apply once the request completes.

💡 Best Practices