Removing the Confusion Between JQuery Ajax success:, .success() and .done()

There is a lot of confusion on the use of the jQuery success: callback event option. We recently edited a StackOverflow answer related to this and thought we would consolidate the clarification here as well.

The success: Callback Event Option

Below is the the Ajax success: local callback event option. It is not deprecated. It’s fine to use within your Ajax callbacks. Here’s its usage:

$.ajax({
    url: 'js/json.txt',
    type: 'GET'
    success: function(data){
        console.log( data )
        $( '#output' ).html( data );
    }
});

It is defined as an option within the ajax call. In colloquial usage, developers call it an Ajax “property” or “parameter” ¹. The JQuery Ajax documentation specifically refers to success: as a local event and defines it as a function to be called if the request succeeds.

Using .done() as an Alternative to the success: Callback Event Option

The below is what’s called the .done() deferred object method. It’s an alternative construct to the success: callback event option:

$.ajax({
    url: 'js/json.txt',
    type: 'GET'
})
.done(function(data){
    console.log( data )
    $( '#output' ).html( data );
});

One of its advantages over the success: callback event option is that .done() allows chaining.

Other deferred object methods include .always(), and .fail(). These callback methods take one or more function arguments that are called when the $.ajax() request terminates.

So What Has Been Deprecated?

AJAX state change methods on JQuery XML HTTP Request (jqXHR) object have been deprecated. Methods related to state changes include .success, .error and .complete. Here is the official notice excerpted the JQuery Ajax documentation

Deprecation Notice: The jqXHR.success(), jqXHR.error(), and jqXHR.complete() callbacks are removed as of jQuery 3.0. You can use jqXHR.done(), jqXHR.fail(), and jqXHR.always() instead

---

¹To be precise, a property is the name given to variable used within an object. While parameters are variables within a function definition (i.e., function foo(parameter_1, parameter_2){}) that receive arguments sent by function calls such as foo(argument_1, argument_2).

---