Why can I run multiple functions on one line on a single jQuery object?

Question

E.g.: $(".element").fadeOut().delay(500).fadeIn();

Why can I run multiple functions on a single jQuery object and when can I use this feature? Is there any tutorial/documentation on this?

Answer 1

This is known as chaining and helps you create a fluent interface. Each function returns a reference to the current jQuery instance, which is why you can chain the calls together.

You first create a jQuery instance using $('.element'), which returns an insance of the jQuery object; it's essentially like a constructor. Then each member function of the jQuery object, returns a reference to this, which is basically the owning instance of that function. So instead of doing this:

var jQueryObj = $(".element");
jQueryObj.fadeOut();
jQueryObj.delay(500);
jQueryObj.fadeIn();

You can do it all in one line, because each function more-or-less kind of looks like this (this is a very simple example):

function fadeOut() {
   //jQuery code
   //...

   return this;
}

It is important to note that not all jQuery functions are chainable; some do not return a reference to the jQuery instance and so you cannot chain them. Examples include .html(), .text(), and .val(). These return the actual content that you want (HTML, text, or value of an input element for example). It wouldn't make sense to chain in these cases.

Here's a very simple example that shows you how chaining works:

var Starship = function() {
    this.name = "USS Enterprise";
    this.registry = "NCC-1701";
    this.shipClass = "Constitution";
};

Starship.prototype.name = function(name) {
    this.name = name;
    return this;
};

Starship.prototype.registry = function(registry) {
    this.registry = registry;
    return this;
}

Starship.prototype.shipClass = function(shipClass) {
    this.shipClass = shipClass;
    return this;
}

Starship.prototype.print = function() {
    console.log(this.name + " " + this. registry + " " + this.shipClass);
}

Now you can create an instance like so:

var starship = new Starship()
    .name("USS Enterprise")
    .registry("NCC-1701-E")
    .shipClass("Sovereign");

You can then also call starship.print(), but notice that it does not return this, which means you cannot chain anything after that.

jQuery's documentation will go over which methods are chainable and which are not. If the documentation says that the function returns jQuery, then it is chainable; otherwise it is not. Also take note that certain methods are chainable depending on what parameters are passed. For example, the .attr function, which lets you set an attribute, is chainable only when setting an attribute via .attr(attrName, attrValue). When only supplying one argument (.attr(attrName)), it returns the value of the attribute and hence is not chainable.