jQuery

Deferred object

The Deferred object is a chainable utility object. It can register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.

Instance of Deffered can be created by calling the jQuery.Deferred([cbBeforeStart]) method.

Ajax methods of jQuery return a jqXHR object, which is derived from a Deferred object.

The jQuery.when(deferreds) method provides a way to execute callback functions based on zero or more Thenable objects, usually Deferred objects that represent asynchronous events.

function asyncEvent() {
  var dfd = jQuery.Deferred();
 
  // Resolve after a random interval
  setTimeout(function() {
    dfd.resolve( "hurray" );
  }, Math.floor( 400 + Math.random() * 2000 ) );
 
  // Reject after a random interval
  setTimeout(function() {
    dfd.reject( "sorry" );
  }, Math.floor( 400 + Math.random() * 2000 ) );
 
  // Show a "working..." message every half-second
  setTimeout(function working() {
    if ( dfd.state() === "pending" ) {
      dfd.notify( "working... " );
      setTimeout( working, 500 );
    }
  }, 1 );
 
  // Return the Promise so caller can't change the Deferred
  return dfd.promise();
}
 
// Attach a done, fail, and progress handler for the asyncEvent
$.when( asyncEvent() ).then(
  function( status ) {
    alert( status + ", things are going well" );
  },
  function( status ) {
    alert( status + ", you fail this time" );
  },
  function( status ) {
    $( "body" ).append( status );
  }
);
method description
catch(func) Add function to be called when the Deferred object is rejected.
fail(cbFail [, cbFail]) Add handlers to be called when the Deferred object is rejected. The cbFail parameter is function of array or functions, that are called when the Deferred is rejected.
done(cbDone [, cbDone]) Add handlers to be called when the Deferred object is resolved. The cbDone parameter is function of array or functions, that are called when the Deferred is resolved.
always(cbAlways [,cbAlways]) Add handlers to be called when the Deferred object is either resolved or rejected. The cbDone parameter is function or array of functions, that is called when the Deferred is resolved or rejected.
then(cbDone [, cbFail] [, cbProgress]) Add handlers to be called when the Deferred object is resolved, rejected, or still in progress. This method syntax was added in version 1.8.
progress(cbProgress [, cbProgress]) Add handlers to be called when the Deferred object generates progress notifications. The cbProgress parameter is function or array of functions to be called when the Deferred generates progress notifications.
reject([args]) Reject a Deferred object and call any cbFail callbacks with the given args (array of arguments). Normally, only the creator of a Deferred should call this method.
rejectWith(context [, args]) Reject a Deferred object and call any cbFail callbacks with the given contextcontext and args (array of arguments).The context parameter will be passed to the cbFail as the this object. Normally, only the creator of a Deferred should call this method.
resolve([args]) Resolve a Deferred object and call any cbDone callbacks with the given args (array of arguments). Normally, only the creator of a Deferred should call this method.
resolveWith(context [, args]) Resolve a Deferred object and call any cbDone callbacks with the given context and args (array of arguments). The context parameter will be passed to the cbDone as the this object. Normally, only the creator of a Deferred should call this method.
notify([args]) Call the cbProgress callbacks on a Deferred object with the given args (array of arguments). Normally, only the creator of a Deferred should call this method.
notifyWith(context [, args]) Call the cbProgress callbacks on a Deferred object with the given context and args (array of arguments). The context parameter will be passed to the cbProgress as the this object. Normally, only the creator of a Deferred should call this method.
state() Returns string with the current state of a Deferred object. Possible values are:
  • pending - the Deferred object is not yet in a completed state
  • resolved - the Deferred object is in the resolved state, meaning that either deferred.resolve() or deferred.resolveWith() has been called for the object and the cbDone callbacks have been called
  • rejected - the Deferred object is in the rejected state, meaning that either deferred.reject() or deferred.rejectWith() has been called for the object and the cbFail callbacks have been called
promise([target]) Returns a Deferred's Promise object.