Given a jQuery object that represents a set of DOM elements, the .add() method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to .add() can be pretty much anything that $() accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.

Do not assume that this method appends the elements to the existing collection in the order they are passed to the .add() method. When all elements are members of the same document, the resulting collection from .add() will be sorted in document order; that is, in order of each element's appearance in the document. If the collection consists of elements from different documents or ones not in any document, the sort order is undefined. To create a jQuery object with elements in a well-defined order, use the $(array_of_DOM_elements) signature.

The updated set of elements can be used in a following (chained) method, or assigned to a variable for later use. For example:

      
$("p").add("div").addClass("widget");
var pdiv = $("p").add("div");

    

The following will not save the added elements, because the .add() method creates a new set and leaves the original set in pdiv unchanged:

      
var pdiv = $("p");
pdiv.add("div");  // WRONG, pdiv will not change

    

Consider a page with a simple list and a paragraph following it:

      <ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
</ul>
<p>a paragraph</p>
    

We can select the list items and then the paragraph by using either a selector or a reference to the DOM element itself as the .add() method's argument:

      $('li').add('p').css('background-color', 'red');
    

Or:

      $('li').add(document.getElementsByTagName('p')[0])
  .css('background-color', 'red');
    

The result of this call is a red background behind all four elements. Using an HTML snippet as the .add() method's argument (as in the third version), we can create additional elements on the fly and add those elements to the matched set of elements. Let's say, for example, that we want to alter the background of the list items along with a newly created paragraph:

      $('li').add('<p id="new">new paragraph</p>')
  .css('background-color', 'red');
    

Although the new paragraph has been created and its background color changed, it still does not appear on the page. To place it on the page, we could add one of the insertion methods to the chain.

As of jQuery 1.4 the results from .add() will always be returned in document order (rather than a simple concatenation).

Note: To reverse the .add() you can use .not( elements | selector ) to remove elements from the jQuery results, or .end() to return to the selection before you added.

It's important to note that this method does not replace a class. It simply adds the class, appending it to any which may already be assigned to the elements.

More than one class may be added at a time, separated by a space, to the set of matched elements, like so:

$("p").addClass("myClass yourClass");

This method is often used with .removeClass() to switch elements' classes from one to another, like so:

$("p").removeClass("myClass noClass").addClass("yourClass");

Here, the myClass and noClass classes are removed from all paragraphs, while yourClass is added.

As of jQuery 1.4, the .addClass() method's argument can receive a function.

$("ul li").addClass(function(index) {
  return "item-" + index;
});

Given an unordered list with two <li> elements, this example adds the class "item-0" to the first <li> and "item-1" to the second.

The .after() and .insertAfter() methods perform the same task. The major difference is in the syntax—specifically, in the placement of the content and target. With .after(), the selector expression preceding the method is the container after which the content is inserted. With .insertAfter(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted after the target container.

Using the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

Content can be created and then inserted after several elements at once:

$('.inner').after('<p>Test</p>');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
  <p>Test</p>
</div>

An element in the DOM can also be selected and inserted after another element:

$('.container').after($('h2'));

If an element selected this way is inserted into a single location elsewhere in the DOM, it will be moved rather than cloned:

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Inserting Disconnected DOM nodes

As of jQuery 1.4, .before() and .after() will also work on disconnected DOM nodes. For example, given the following code:

$('<div/>').after('<p></p>');

The result is a jQuery set containing a div and a paragraph, in that order. That set can be further manipulated, even before it is inserted in the document.

$('<div/>').after('<p></p>').addClass('foo')
  .filter('p').attr('id', 'bar').html('hello')
.end()
.appendTo('body');

This results in the following elements inserted just before the closing </body> tag:

<div class="foo"></div>
<p class="foo" id="bar">hello</p>

Passing a Function

As of jQuery 1.4, .after() supports passing a function that returns the elements to insert.

$('p').after(function() {
  return '<div>' + this.className + '</div>';
});

This example inserts a <div> after each paragraph, with each new <div> containing the class name(s) of its preceding paragraph.

Additional Arguments

Similar to other content-adding methods such as .prepend() and .before(), .after() also supports passing in multiple arguments as input. Supported input includes DOM elements, jQuery objects, HTML strings, and arrays of DOM elements.

For example, the following will insert two new <div>s and an existing <div> after the first paragraph:

var $newdiv1 = $('<div id="object1"/>'),
    newdiv2 = document.createElement('div'),
    existingdiv1 = document.getElementById('foo');

$('p').first().after($newdiv1, [newdiv2, existingdiv1]);

Since .after() can accept any number of additional arguments, the same result can be achieved by passing in the three <div>s as three separate arguments, like so: $('p').first().after($newdiv1, newdiv2, existingdiv1). The type and number of arguments will largely depend on the elements that are collected in the code.

Whenever an Ajax request completes, jQuery triggers the ajaxComplete event. Any and all handlers that have been registered with the .ajaxComplete() method are executed at this time.

To observe this method in action, set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

Attach the event handler to the document:

$(document).ajaxComplete(function() {
  $( ".log" ).text( "Triggered ajaxComplete handler." );
});

Now, make an Ajax request using any jQuery method:

$( ".trigger" ).click(function() {
  $( ".result" ).load( "ajax/test.html" );
});

When the user clicks the element with class trigger and the Ajax request completes, the log message is displayed.

As of jQuery 1.8, the .ajaxComplete() method should only be attached to document.

All ajaxComplete handlers are invoked, regardless of what Ajax request was completed. If you must differentiate between the requests, use the parameters passed to the handler. Each time an ajaxComplete handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, you can restrict the callback to only handling events dealing with a particular URL:

$(document).ajaxComplete(function(event, xhr, settings) {
  if ( settings.url === "ajax/test.html" ) {
    $( ".log" ).text( "Triggered ajaxComplete handler. The result is " +
                     xhr.responseHTML );
  }
});

Note: You can get the returned ajax contents by looking at xhr.responseXML or xhr.responseHTML for xml and html respectively.

Whenever an Ajax request completes with an error, jQuery triggers the ajaxError event. Any and all handlers that have been registered with the .ajaxError() method are executed at this time. Note: This handler is not called for cross-domain script and cross-domain JSONP requests.

To observe this method in action, set up a basic Ajax load request.

<button class="trigger">Trigger</button>
<div class="result"></div>
<div class="log"></div>

Attach the event handler to the document:

$(document).ajaxError(function() {
  $( "div.log" ).text( "Triggered ajaxError handler." );
});

Now, make an Ajax request using any jQuery method:

$( "button.trigger" ).on( "click", function() {
  $( "div.result" ).load( "ajax/missing.html" );
});

When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.

As of jQuery 1.8, the .ajaxError() method should only be attached to document.

All ajaxError handlers are invoked, regardless of what Ajax request was completed. To differentiate between the requests, use the parameters passed to the handler. Each time an ajaxError handler is executed, it is passed the event object, the jqXHR object (prior to jQuery 1.5, the XHR object), and the settings object that was used in the creation of the request. When an HTTP error occurs, the fourth argument (thrownError) receives the textual portion of the HTTP status, such as "Not Found" or "Internal Server Error." For example, to restrict the error callback to only handling events dealing with a particular URL:

$( document ).ajaxError(function(event, jqxhr, settings, exception) {
  if ( settings.url == "ajax/missing.html" ) {
    $( "div.log" ).text( "Triggered ajaxError handler." );
  }
});

Whenever an Ajax request is about to be sent, jQuery triggers the ajaxSend event. Any and all handlers that have been registered with the .ajaxSend() method are executed at this time.

To observe this method in action, set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

Attach the event handler to the document:

$(document).ajaxSend(function() {
  $( ".log" ).text( "Triggered ajaxSend handler." );
});

Now, make an Ajax request using any jQuery method:

$( ".trigger" ).click(function() {
  $( ".result" ).load( "ajax/test.html" );
});

When the user clicks the element with class trigger and the Ajax request is about to begin, the log message is displayed.

As of jQuery 1.8, the .ajaxSend() method should only be attached to document.

All ajaxSend handlers are invoked, regardless of what Ajax request is to be sent. If you must differentiate between the requests, use the parameters passed to the handler. Each time an ajaxSend handler is executed, it is passed the event object, the jqXHR object (in version 1.4, XMLHttpRequestobject), and the settings object that was used in the creation of the Ajax request. For example, you can restrict the callback to only handling events dealing with a particular URL:

$(document).ajaxSend(function(event, jqxhr, settings) {
  if ( settings.url == "ajax/test.html" ) {
    $( ".log" ).text( "Triggered ajaxSend handler." );
  }
});

Whenever an Ajax request is about to be sent, jQuery checks whether there are any other outstanding Ajax requests. If none are in progress, jQuery triggers the ajaxStart event. Any and all handlers that have been registered with the .ajaxStart() method are executed at this time.

To observe this method in action, set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

Attach the event handler to any element:

$(document).ajaxStart(function() {
  $( ".log" ).text( "Triggered ajaxStart handler." );
});

Now, make an Ajax request using any jQuery method:

$( ".trigger" ).click(function() {
  $( ".result" ).load("ajax/test.html");
});

When the user clicks the element with class trigger and the Ajax request is sent, the log message is displayed.

As of jQuery 1.8, the .ajaxStart() method should only be attached to document.

Whenever an Ajax request completes, jQuery checks whether there are any other outstanding Ajax requests. If none remain, jQuery triggers the ajaxStop event. Any and all handlers that have been registered with the .ajaxStop() method are executed at this time. The ajaxStop event is also triggered if the last outstanding Ajax request is cancelled by returning false within the beforeSend callback function.

To observe this method in action, set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

Attach the event handler to the document:

$( ".log" ).ajaxStop(function() {
  $(this).text( "Triggered ajaxStop handler." );
});

Now, make an Ajax request using any jQuery method:

$( ".trigger" ).click(function() {
  $( ".result" ).load( "ajax/test.html" );
});

When the user clicks the element with class trigger and the Ajax request completes, the log message is displayed.

As of jQuery 1.8, the .ajaxStop() method should only be attached to document.

Whenever an Ajax request completes successfully, jQuery triggers the ajaxSuccess event. Any and all handlers that have been registered with the .ajaxSuccess() method are executed at this time.

To observe this method in action, set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

Attach the event handler to any element:

$(document).ajaxSuccess(function() {
  $( ".log" ).text( "Triggered ajaxSuccess handler." );
});

Now, make an Ajax request using any jQuery method:

$( ".trigger" ).on("click", function() {
  $( ".result" ).load( "ajax/test.html" );
});

When the user clicks the element with class trigger and the Ajax request completes successfully, the log message is displayed.

As of jQuery 1.8, the .ajaxSuccess() method should only be attached to document.

All ajaxSuccess handlers are invoked, regardless of what Ajax request was completed. If you must differentiate between the requests, you can use the parameters passed to the handler. Each time an ajaxSuccess handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, you can restrict the callback to only handling events dealing with a particular URL:

$(document).ajaxSuccess(function(event, xhr, settings) {
  if ( settings.url == "ajax/test.html" ) {
    $( ".log" ).text( "Triggered ajaxSuccess handler. The ajax response was: " +
                      xhr.responseText );
  }
});

Note: You can get the returned ajax contents by looking at xhr.responseXML or xhr.responseText for xml and html respectively.

Caution: The all, or universal, selector is extremely slow, except when used by itself.

Note: This function has been deprecated and is now an alias for .addBack(), which should be used with jQuery 1.8 and later.

As described in the discussion for .end(), jQuery objects maintain an internal stack that keeps track of changes to the matched set of elements. When one of the DOM traversal methods is called, the new set of elements is pushed onto the stack. If the previous set of elements is desired as well, .andSelf() can help.

Consider a page with a simple list on it:

<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

The result of the following code is a red background behind items 3, 4 and 5:

$('li.third-item').nextAll().andSelf()
  .css('background-color', 'red');

First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to .nextAll() then pushes the set of items 4 and 5 onto the stack. Finally, the .andSelf() invocation merges these two sets together, creating a jQuery object that points to all three items in document order: {[<li.third-item>,<li>,<li> ]}.

The .animate() method allows us to create animation effects on any numeric CSS property. The only required parameter is a plain object of CSS properties. This object is similar to the one that can be sent to the .css() method, except that the range of properties is more restrictive.

Animation Properties and Values

All animated properties should be animated to a single numeric value, except as noted below; most properties that are non-numeric cannot be animated using basic jQuery functionality (For example, width, height, or left can be animated but background-color cannot be, unless the jQuery.Color() plugin is used). Property values are treated as a number of pixels unless otherwise specified. The units em and % can be specified where applicable.

In addition to style properties, some non-style properties such as scrollTop and scrollLeft, as well as custom properties, can be animated.

Shorthand CSS properties (e.g. font, background, border) are not fully supported. For example, if you want to animate the rendered border width, at least a border style and border width other than "auto" must be set in advance. Or, if you want to animate font size, you would use fontSize or the CSS equivalent 'font-size' rather than simply 'font'.

In addition to numeric values, each property can take the strings 'show', 'hide', and 'toggle'. These shortcuts allow for custom hiding and showing animations that take into account the display type of the element. In order to use jQuery's built-in toggle state tracking, the 'toggle' keyword must be consistently given as the value of the property being animated.

Animated properties can also be relative. If a value is supplied with a leading += or -= sequence of characters, then the target value is computed by adding or subtracting the given number from the current value of the property.

Duration

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The default duration is 400 milliseconds. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

Complete Function

If supplied, the complete callback function is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, the callback is executed once per matched element, not once for the animation as a whole.

Basic Usage

To animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123"
  style="position: relative; left: 10px;" />

To animate the opacity, left offset, and height of the image simultaneously:

$('#clickme').click(function() {
  $('#book').animate({
    opacity: 0.25,
    left: '+=50',
    height: 'toggle'
  }, 5000, function() {
    // Animation complete.
  });
});

Note that the target value of the height property is 'toggle'. Since the image was visible before, the animation shrinks the height to 0 to hide it. A second click then reverses this transition:

The opacity of the image is already at its target value, so this property is not animated by the second click. Since the target value for left is a relative value, the image moves even farther to the right during this second animation.

Directional properties (top, right, bottom, left) have no discernible effect on elements if their position style property is static, which it is by default.

Step Function

The second version of .animate() provides a step option — a callback function that is fired at each step of the animation. This function is useful for enabling custom animation types or altering the animation as it is occurring. It accepts two arguments (now and fx), and this is set to the DOM element being animated.

• now: the numeric value of the property being animated at each step
• fx: a reference to the jQuery.fx prototype object, which contains a number of properties such as elem for the animated element, start and end for the first and last value of the animated property, respectively, and prop for the property being animated.

Note that the step function is called for each animated property on each animated element. For example, given two list items, the step function fires four times at each step of the animation:

$('li').animate({
  opacity: .5,
  height: '50%'
},
{
  step: function(now, fx) {
    var data = fx.elem.id + ' ' + fx.prop + ': ' + now;
    $('body').append('<div>' + data + '</div>');
  }
});

Easing

The remaining parameter of .animate() is a string naming an easing function to use. An easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.

Per-property Easing

As of jQuery version 1.4, you can set per-property easing functions within a single .animate() call. In the first version of .animate(), each property can take an array as its value: The first member of the array is the CSS property and the second member is an easing function. If a per-property easing function is not defined for a particular property, it uses the value of the .animate() method's optional easing argument. If the easing argument is not defined, the default swing function is used.

For example, to simultaneously animate the width and height with the swing easing function and the opacity with the linear easing function:

$('#clickme').click(function() {
  $('#book').animate({
    width: ['toggle', 'swing'],
    height: ['toggle', 'swing'],
    opacity: 'toggle'
  }, 5000, 'linear', function() {
      $(this).after('<div>Animation complete.</div>');
  });
});

In the second version of .animate(), the options object can include the specialEasing property, which is itself an object of CSS properties and their corresponding easing functions. For example, to simultaneously animate the width using the linear easing function and the height using the easeOutBounce easing function:

$('#clickme').click(function() {
  $('#book').animate({
    width: 'toggle',
    height: 'toggle'
  }, {
    duration: 5000,
    specialEasing: {
      width: 'linear',
      height: 'easeOutBounce'
    },
    complete: function() {
      $(this).after('<div>Animation complete.</div>');
    }
  });
});

As previously noted, a plugin is required for the easeOutBounce function.

Note: If you use a custom jQuery build without the effects module, the :animated selector will throw an error.

The .append() method inserts the specified content as the last child of each element in the jQuery collection (To insert it as the first child, use .prepend()).

The .append() and .appendTo() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .append(), the selector expression preceding the method is the container into which the content is inserted. With .appendTo(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.

Consider the following HTML:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

You can create content and insert it into several elements at once:

$('.inner').append('<p>Test</p>');

Each inner <div> element gets this new content:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">
    Hello
    <p>Test</p>
  </div>
  <div class="inner">
    Goodbye
    <p>Test</p>
  </div>
</div>

You can also select an element on the page and insert it into another:

$('.container').append($('h2'));

If an element selected this way is inserted into a single location elsewhere in the DOM, it will be moved into the target (not cloned):

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
  <h2>Greetings</h2>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Additional Arguments

Similar to other content-adding methods such as .prepend() and .before(), .append() also supports passing in multiple arguments as input. Supported input includes DOM elements, jQuery objects, HTML strings, and arrays of DOM elements.

For example, the following will insert two new <div>s and an existing <div> as the last three child nodes of the body:

var $newdiv1 = $('<div id="object1"/>'),
    newdiv2 = document.createElement('div'),
    existingdiv1 = document.getElementById('foo');

$('body').append($newdiv1, [newdiv2, existingdiv1]);

Since .append() can accept any number of additional arguments, the same result can be achieved by passing in the three <div>s as three separate arguments, like so: $('body').append($newdiv1, newdiv2, existingdiv1). The type and number of arguments will largely depend on how you collect the elements in your code.

The .append() and .appendTo() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .append(), the selector expression preceding the method is the container into which the content is inserted. With .appendTo(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.

Consider the following HTML:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once:

$('<p>Test</p>').appendTo('.inner');

Each inner <div> element gets this new content:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">
    Hello
    <p>Test</p>
  </div>
  <div class="inner">
    Goodbye
    <p>Test</p>
  </div>
</div>

We can also select an element on the page and insert it into another:

$('h2').appendTo($('.container'));

If an element selected this way is inserted into a single location elsewhere in the DOM, it will be moved into the target (not cloned) and a new set consisting of the inserted element is returned:

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
  <h2>Greetings</h2>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first, and that new set (the original element plus clones) is returned.

Before jQuery 1.9, the append-to-single-element case did not create a new set, but instead returned the original set which made it difficult to use the .end() method reliably when being used with an unknown number of elements.

The .attr() method gets the attribute value for only the first element in the matched set. To get the value for each element individually, use a looping construct such as jQuery's .each() or .map() method.

Using jQuery's .attr() method to get the value of an element's attribute has two main benefits:

1. Convenience: It can be called directly on a jQuery object and chained to other jQuery methods.
2. Cross-browser consistency: The values of some attributes are reported inconsistently across browsers, and even across versions of a single browser. The .attr() method reduces such inconsistencies.

As of jQuery 1.6, the .attr() method returns undefined for attributes that have not been set. To retrieve and change DOM properties such as the checked, selected, or disabled state of form elements, use the .prop() method.

Attributes vs. Properties

The difference between attributes and properties can be important in specific situations. Before jQuery 1.6, the .attr() method sometimes took property values into account when retrieving some attributes, which could cause inconsistent behavior. As of jQuery 1.6, the .prop() method provides a way to explicitly retrieve property values, while .attr() retrieves attributes.

For example, selectedIndex, tagName, nodeName, nodeType, ownerDocument, defaultChecked, and defaultSelected should be retrieved and set with the .prop() method. Prior to jQuery 1.6, these properties were retrievable with the .attr() method, but this was not within the scope of attr. These do not have corresponding attributes and are only properties.

Concerning boolean attributes, consider a DOM element defined by the HTML markup <input type="checkbox" checked="checked" />, and assume it is in a JavaScript variable named elem:

According to the W3C forms specification, the checked attribute is a boolean attribute, which means the corresponding property is true if the attribute is present at all—even if, for example, the attribute has no value or is set to empty string value or even "false". This is true of all boolean attributes.

Nevertheless, the most important concept to remember about the checked attribute is that it does not correspond to the checked property. The attribute actually corresponds to the defaultChecked property and should be used only to set the initial value of the checkbox. The checked attribute value does not change with the state of the checkbox, while the checked property does. Therefore, the cross-browser-compatible way to determine if a checkbox is checked is to use the property:

• if ( elem.checked )
• if ( $(elem).prop("checked") )
• if ( $(elem).is(":checked") )

The same is true for other dynamic attributes, such as selected and value.

The .attr() method is a convenient way to set the value of attributes—especially when setting multiple attributes or using values returned by a function. Consider the following image:

<img id="greatphoto" src="brush-seller.jpg" alt="brush seller" />

Setting a simple attribute

To change the alt attribute, simply pass the name of the attribute and its new value to the .attr() method:

$('#greatphoto').attr('alt', 'Beijing Brush Seller');

Add an attribute the same way:

$('#greatphoto')
.attr('title', 'Photo by Kelly Clark');

Setting several attributes at once

To change the alt attribute and add the title attribute at the same time, pass both sets of names and values into the method at once using a plain JavaScript object. Each key-value pair in the object adds or modifies an attribute:

$('#greatphoto').attr({
  alt: 'Beijing Brush Seller',
  title: 'photo by Kelly Clark'
});

When setting multiple attributes, the quotes around attribute names are optional.

WARNING: When setting the 'class' attribute, you must always use quotes!

Note: jQuery prohibits changing the type attribute on an <input> or <button> element and will throw an error in all browsers. This is because the type attribute cannot be changed in Internet Explorer.

Computed attribute values

By using a function to set attributes, you can compute the value based on other properties of the element. For example, to concatenate a new value with an existing value:

$('#greatphoto').attr('title', function(i, val) {
  return val + ' - photo by Kelly Clark'
});

This use of a function to compute attribute values can be particularly useful when modifying the attributes of multiple elements at once.

Note: If nothing is returned in the setter function (ie. function(index, attr){}), or if undefined is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.

This selector was introduced into the CSS specification to handle language attributes.

This is the most generous of the jQuery attribute selectors that match against a value. It will select an element if the selector's string appears anywhere within the element's attribute value. Compare this selector with the Attribute Contains Word selector (e.g. [attr~="word"]), which is more appropriate in many cases.

This selector matches the test string against each word in the attribute value, where a "word" is defined as a string delimited by whitespace. The selector matches if the test string is exactly equal to any of the words.

This selector is equivalent to :not([attr="value"]).

This selector can be useful for identifying elements in pages produced by server-side frameworks that produce HTML with systematic element IDs. However it will be slower than using a class selector so leverage classes, if you can, to group like elements.

The .before() and .insertBefore() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .before(), the selector expression preceding the method is the container before which the content is inserted. With .insertBefore(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted before the target container.

Consider the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

You can create content and insert it before several elements at once:

$('.inner').before('<p>Test</p>');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <p>Test</p>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
</div>

You can also select an element on the page and insert it before another:

$('.container').before($('h2'));

If an element selected this way is inserted into a single location elsewhere in the DOM, it will be moved before the target (not cloned):

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

In jQuery 1.4, .before() and .after() will also work on disconnected DOM nodes:

$("<div/>").before("<p></p>");

The result is a jQuery set that contains a paragraph and a div (in that order).

Additional Arguments

Similar to other content-adding methods such as .prepend() and .after(), .before() also supports passing in multiple arguments as input. Supported input includes DOM elements, jQuery objects, HTML strings, and arrays of DOM elements.

For example, the following will insert two new <div>s and an existing <div> before the first paragraph:

var $newdiv1 = $('<div id="object1"/>'),
    newdiv2 = document.createElement('div'),
    existingdiv1 = document.getElementById('foo');

$('p').first().before($newdiv1, [newdiv2, existingdiv1]);

Since .before() can accept any number of additional arguments, the same result can be achieved by passing in the three <div>s as three separate arguments, like so: $('p').first().before($newdiv1, newdiv2, existingdiv1). The type and number of arguments will largely depend on how you collect the elements in your code.

As of jQuery 1.7, the .on() method is the preferred method for attaching event handlers to a document. For earlier versions, the .bind() method is used for attaching an event handler directly to elements. Handlers are attached to the currently selected elements in the jQuery object, so those elements must exist at the point the call to .bind() occurs. For more flexible event binding, see the discussion of event delegation in .on() or .delegate().

Any string is legal for eventType; if the string is not the name of a native DOM event, then the handler is bound to a custom event. These events are never called by the browser, but may be triggered manually from other JavaScript code using .trigger() or .triggerHandler().

If the eventType string contains a period (.) character, then the event is namespaced. The period character separates the event from its namespace. For example, in the call .bind('click.name', handler), the string click is the event type, and the string name is the namespace. Namespacing allows us to unbind or trigger some events of a type without affecting others. See the discussion of .unbind() for more information.

There are shorthand methods for some standard browser events such as .click() that can be used to attach or trigger event handlers. For a complete list of shorthand methods, see the events category.

When an event reaches an element, all handlers bound to that event type for the element are fired. If there are multiple handlers registered, they will always execute in the order in which they were bound. After all handlers have executed, the event continues along the normal event propagation path.

A basic usage of .bind() is:

$('#foo').bind('click', function() {
  alert('User clicked on "foo."');
});

This code will cause the element with an ID of foo to respond to the click event. When a user clicks inside this element thereafter, the alert will be shown.

Multiple Events

Multiple event types can be bound at once by including each one separated by a space:

$('#foo').bind('mouseenter mouseleave', function() {
  $(this).toggleClass('entered');
});

The effect of this on <div id="foo"> (when it does not initially have the "entered" class) is to add the "entered" class when the mouse enters the <div> and remove the class when the mouse leaves.

As of jQuery 1.4 we can bind multiple event handlers simultaneously by passing an object of event type/handler pairs:

$('#foo').bind({
  click: function() {
    // do something on click
  },
  mouseenter: function() {
    // do something on mouseenter
  }
});

Event Handlers

The handler parameter takes a callback function, as shown above. Within the handler, the keyword this refers to the DOM element to which the handler is bound. To make use of the element in jQuery, it can be passed to the normal $() function. For example:

$('#foo').bind('click', function() {
  alert($(this).text());
});

After this code is executed, when the user clicks inside the element with an ID of foo, its text contents will be shown as an alert.

As of jQuery 1.4.2 duplicate event handlers can be bound to an element instead of being discarded. This is useful when the event data feature is being used, or when other unique data resides in a closure around the event handler function.

In jQuery 1.4.3 you can now pass in false in place of an event handler. This will bind an event handler equivalent to: function(){ return false; }. This function can be removed at a later time by calling: .unbind( eventName, false ).

The Event object

The handler callback function can also take parameters. When the function is called, the event object will be passed to the first parameter.

The event object is often unnecessary and the parameter omitted, as sufficient context is usually available when the handler is bound to know exactly what needs to be done when the handler is triggered. However, at times it becomes necessary to gather more information about the user's environment at the time the event was initiated. View the full Event Object.

Returning false from a handler is equivalent to calling both .preventDefault() and .stopPropagation() on the event object.

Using the event object in a handler looks like this:

$(document).ready(function() {
  $('#foo').bind('click', function(event) {
    alert('The mouse cursor is at ('
      + event.pageX + ', ' + event.pageY + ')');
  });
});

Note the parameter added to the anonymous function. This code will cause a click on the element with ID foo to report the page coordinates of the mouse cursor at the time of the click.

Passing Event Data

The optional eventData parameter is not commonly used. When provided, this argument allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. For example, suppose we have two event handlers that both refer to the same external variable:

var message = 'Spoon!';
$('#foo').bind('click', function() {
  alert(message);
});
message = 'Not in the face!';
$('#bar').bind('click', function() {
  alert(message);
});

Because the handlers are closures that both have message in their environment, both will display the message Not in the face! when triggered. The variable's value has changed. To sidestep this, we can pass the message in using eventData:

var message = 'Spoon!';
$('#foo').bind('click', {msg: message}, function(event) {
  alert(event.data.msg);
});
message = 'Not in the face!';
$('#bar').bind('click', {msg: message}, function(event) {
  alert(event.data.msg);
});

This time the variable is not referred to directly within the handlers; instead, the variable is passed in by value through eventData, which fixes the value at the time the event is bound. The first handler will now display Spoon! while the second will alert Not in the face!

If eventData is present, it is the second argument to the .bind() method; if no additional data needs to be sent to the handler, then the callback is passed as the second and final argument.

As of jQuery 1.4 we can no longer attach data (and thus, events) to object, embed, or applet elements because critical errors occur when attaching data to Java applets.

Note: Although demonstrated in the next example, it is inadvisable to bind handlers to both the click and dblclick events for the same element. The sequence of events triggered varies from browser to browser, with some receiving two click events before the dblclick and others only one. Double-click sensitivity (maximum time between clicks that is detected as a double click) can vary by operating system and browser, and is often user-configurable.

This method is a shortcut for .on('blur', handler) in the first two variations, and .trigger('blur') in the third.

The blur event is sent to an element when it loses focus. Originally, this event was only applicable to form elements, such as <input>. In recent browsers, the domain of the event has been extended to include all element types. An element can lose focus via keyboard commands, such as the Tab key, or by mouse clicks elsewhere on the page.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Field 1" />
  <input type="text" value="Field 2" />
</form>
<div id="other">
  Trigger the handler
</div>
The event handler can be bound to the first input field:
$('#target').blur(function() {
  alert('Handler for .blur() called.');
});

Now if the first field has the focus, clicking elsewhere or tabbing away from it displays the alert:

Handler for .blur() called.

To trigger the event programmatically, apply .blur() without an argument:

$('#other').click(function() {
  $('#target').blur();
});

After this code executes, clicks on Trigger the handler will also alert the message.

The blur event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the blur event will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mapping blur to the focusout event in its event delegation methods, .live() and .delegate().

An equivalent selector to $(":button") using valid CSS is $("button, input[type='button']").

This method returns the Callbacks object onto which it is attached (this).

Example

Use callbacks.add() to add new callbacks to a callback list:

// a sample logging function to be added to a callbacks list
var foo = function( value ) {
  console.log( "foo: " + value );
};

// another function to also be added to the list
var bar = function( value ){
  console.log( "bar: " + value );
};

var callbacks = $.Callbacks();

// add the function "foo" to the list
callbacks.add( foo );

// fire the items on the list
callbacks.fire( "hello" );
// outputs: "foo: hello"

// add the function "bar" to the list
callbacks.add( bar );

// fire the items on the list again
callbacks.fire( "world" );

// outputs:
// "foo: world"
// "bar: world"

This method returns the Callbacks object onto which it is attached (this).

Example

Use callbacks.disable() to disable further calls to a callback list:

// a sample logging function to be added to a callbacks list
var foo = function( value ) {
  console.log( value );
};

var callbacks = $.Callbacks();

// add the above function to the list
callbacks.add( foo );

// fire the items on the list
callbacks.fire( "foo" );
// outputs: foo

// disable further calls being possible
callbacks.disable();

// attempt to fire with "foobar" as an argument
callbacks.fire( "foobar" );
// foobar isn't output

This method returns the Callbacks object onto which it is attached (this).

Example

Use callbacks.empty() to empty a list of callbacks:

// a sample logging function to be added to a callbacks list
var foo = function( value1, value2 ) {
  console.log( "foo: " + value1 + "," + value2 );
}

// another function to also be added to the list
var bar = function( value1, value2 ){
    console.log( "bar: " + value1 + "," + value2 );
}

var callbacks = $.Callbacks();

// add the two functions
callbacks.add( foo );
callbacks.add( bar );

// empty the callbacks list
callbacks.empty();

// check to ensure all callbacks have been removed
console.log( callbacks.has( foo ) );
// false
console.log( callbacks.has( bar ) );
// false

This method returns the Callbacks object onto which it is attached (this).

Example

Use callbacks.fire() to invoke the callbacks in a list with any arguments that have been passed:

// a sample logging function to be added to a callbacks list
var foo = function( value ) {
  console.log( "foo:" + value );
}

var callbacks = $.Callbacks();

// add the function "foo" to the list
callbacks.add( foo );

// fire the items on the list
callbacks.fire( "hello" ); // outputs: "foo: hello"
callbacks.fire( "world" ); // outputs: "foo: world"

// add another function to the list
var bar = function( value ){
    console.log( "bar:" + value );
}

// add this function to the list
callbacks.add( bar );

// fire the items on the list again
callbacks.fire( "hello again" );
// outputs:
// "foo: hello again"
// "bar: hello again"

This method returns the Callbacks object onto which it is attached (this).

Example

Use callbacks.fireWith() to fire a list of callbacks with a specific context and an array of arguments:

// a sample logging function to be added to a callbacks list
var log = function( value1, value2 ) {
  console.log( "Received: " + value1 + "," + value2 );
};

var callbacks = $.Callbacks();

// add the log method to the callbacks list
callbacks.add( log );

// fire the callbacks on the list using the context "window"
// and an arguments array

callbacks.fireWith( window, ["foo","bar"]);

// outputs: "Received: foo, bar"

Example

Use callbacks.fired() to determine if the callbacks in a list have been called at least once:

// a sample logging function to be added to a callbacks list
var foo = function( value ) {
  console.log( "foo:" + value );
};

var callbacks = $.Callbacks();

// add the function "foo" to the list
callbacks.add( foo );

// fire the items on the list
callbacks.fire( "hello" ); // outputs: "foo: hello"
callbacks.fire( "world" ); // outputs: "foo: world"

// test to establish if the callbacks have been called
console.log( callbacks.fired() );

This method returns the Callbacks object onto which it is attached (this).

If the Callbacks object is created with the "memory" flag as its argument, additional functions may be added and fired after the callback list is locked.

This method returns the Callbacks object onto which it is attached (this).

This method is a shortcut for .on('change', handler) in the first two variations, and .trigger('change') in the third.

The change event is sent to an element when its value changes. This event is limited to <input> elements, <textarea> boxes and <select> elements. For select boxes, checkboxes, and radio buttons, the event is fired immediately when the user makes a selection with the mouse, but for the other element types the event is deferred until the element loses focus.

For example, consider the HTML:

<form>
  <input class="target" type="text" value="Field 1" />
  <select class="target">
    <option value="option1" selected="selected">Option 1</option>
    <option value="option2">Option 2</option>
  </select>
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the text input and the select box:

$('.target').change(function() {
  alert('Handler for .change() called.');
});

Now when the second option is selected from the dropdown, the alert is displayed. It is also displayed if you change the text in the field and then click away. If the field loses focus without the contents having changed, though, the event is not triggered. To trigger the event manually, apply .change() without arguments:

$('#other').click(function() {
  $('.target').change();
});

After this code executes, clicks on Trigger the handler will also alert the message. The message will display twice, because the handler has been bound to the change event on both of the form elements.

As of jQuery 1.4, the change event bubbles in Internet Explorer, behaving consistently with the event in other modern browsers.

$(':checkbox') is equivalent to $('[type=checkbox]'). As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':checkbox') is equivalent to $('*:checkbox'), so $('input:checkbox') should be used instead.

The :checked selector works for checkboxes, radio buttons, and select elements. For select elements only, use the :selected selector.

As a CSS selector, the child combinator is supported by all modern web browsers including Safari, Firefox, Opera, Chrome, and Internet Explorer 7 and above, but notably not by Internet Explorer versions 6 and below. However, in jQuery, this selector (along with all others) works across all supported browsers, including IE6.

The child combinator (E > F) can be thought of as a more specific form of the descendant combinator (E F) in that it selects only first-level descendants.

Given a jQuery object that represents a set of DOM elements, the .children() method allows us to search through the children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .children() method differs from .find() in that .children() only travels a single level down the DOM tree while .find() can traverse down multiple levels to select descendant elements (grandchildren, etc.) as well. Note also that like most jQuery methods, .children() does not return text nodes; to get all children including text and comment nodes, use .contents().

The .children() method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a basic nested list on it:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at the level-2 list, we can find its children:

$('ul.level-2').children().css('background-color', 'red');

The result of this call is a red background behind items A, B, and C. Since we do not supply a selector expression, all of the children are part of the returned jQuery object. If we had supplied one, only the matching items among these three would be included.

For class selectors, jQuery uses JavaScript's native getElementsByClassName() function if the browser supports it.

When the .clearQueue() method is called, all functions on the queue that have not been executed are removed from the queue. When used without an argument, .clearQueue() removes the remaining functions from fx, the standard effects queue. In this way it is similar to .stop(true). However, while the .stop() method is meant to be used only with animations, .clearQueue() can also be used to remove any function that has been added to a generic jQuery queue with the .queue() method.

This method is a shortcut for .on('click', handler) in the first two variations, and .trigger('click') in the third. The click event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed and released. Any HTML element can receive this event. For example, consider the HTML:

<div id="target">
  Click here
</div>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to any <div>:

$("#target").click(function() {
  alert("Handler for .click() called.");
});

Now if we click on this element, the alert is displayed:

Handler for .click() called.

We can also trigger the event when a different element is clicked:

$("#other").click(function() {
  $("#target").click();
});

After this code executes, clicks on Trigger the handler will also alert the message.

The click event is only triggered after this exact series of events:

• The mouse button is depressed while the pointer is inside the element.
• The mouse button is released while the pointer is inside the element.

This is usually the desired sequence before taking an action. If this is not required, the mousedown or mouseup event may be more suitable.

The .clone() method performs a deep copy of the set of matched elements, meaning that it copies the matched elements as well as all of their descendant elements and text nodes. For performance reasons, the dynamic state of form elements (e.g., user data typed into input, and textarea or user selections made to a select) is not copied to the cloned elemements. The clone operation sets these fields to their default values as specified in the HTML.

When used in conjunction with one of the insertion methods, .clone() is a convenient way to duplicate elements on a page. Consider the following HTML:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">Goodbye</div>
</div>

As shown in the discussion for .append(), normally when an element is inserted somewhere in the DOM, it is moved from its old location. So, given the code:

$('.hello').appendTo('.goodbye');

The resulting DOM structure would be:

<div class="container">
  <div class="goodbye">
    Goodbye
    <div class="hello">Hello</div>
  </div>
</div>

To prevent this and instead create a copy of the element, you could write the following:

$('.hello').clone().appendTo('.goodbye');

This would produce:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">
    Goodbye
    <div class="hello">Hello</div>
  </div>
</div>

Normally, any event handlers bound to the original element are not copied to the clone. The optional withDataAndEvents parameter allows us to change this behavior, and to instead make copies of all of the event handlers as well, bound to the new copy of the element. As of jQuery 1.4, all element data (attached by the .data() method) is also copied to the new copy.

However, objects and arrays within element data are not copied and will continue to be shared between the cloned element and the original element. To deep copy all data, copy each one manually:

var $elem = $('#elem').data( "arr": [ 1 ] ), // Original element with attached data
    $clone = $elem.clone( true )
    .data( "arr", $.extend( [], $elem.data("arr") ) ); // Deep copy to prevent data sharing

As of jQuery 1.5, withDataAndEvents can be optionally enhanced with deepWithDataAndEvents to copy the events and data for all children of the cloned element.

Given a jQuery object that represents a set of DOM elements, the .closest() method searches through these elements and their ancestors in the DOM tree and constructs a new jQuery object from the matching elements. The .parents() and .closest() methods are similar in that they both traverse up the DOM tree. The differences between the two, though subtle, are significant:

<ul id="one" class="level-1">
  <li class="item-i">I</li>
  <li id="ii" class="item-ii">II
  <ul class="level-2">
    <li class="item-a">A</li>
    <li class="item-b">B
      <ul class="level-3">
        <li class="item-1">1</li>
        <li class="item-2">2</li>
        <li class="item-3">3</li>
      </ul>
    </li>
    <li class="item-c">C</li>
  </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

Suppose we perform a search for <ul> elements starting at item A:

$('li.item-a').closest('ul')
  .css('background-color', 'red');

This will change the color of the level-2 <ul>, since it is the first encountered when traveling up the DOM tree.

Suppose we search for an <li> element instead:

$('li.item-a').closest('li')
  .css('background-color', 'red');

This will change the color of list item A. The .closest() method begins its search with the element itself before progressing up the DOM tree, and stops when item A matches the selector.

We can pass in a DOM element as the context within which to search for the closest element.

var listItemII = document.getElementById('ii');
$('li.item-a').closest('ul', listItemII)
  .css('background-color', 'red');
$('li.item-a').closest('#one', listItemII)
  .css('background-color', 'green');

This will change the color of the level-2 <ul>, because it is both the first <ul> ancestor of list item A and a descendant of list item II. It will not change the color of the level-1 <ul>, however, because it is not a descendant of list item II.

This signature (only!) is deprecated as of jQuery 1.7 and removed in jQuery 1.8. It was primarily meant to be used internally or by plugin authors.

The matching text can appear directly within the selected element, in any of that element's descendants, or a combination thereof. As with attribute value selectors, text inside the parentheses of :contains() can be written as a bare word or surrounded by quotation marks. The text must have matching case to be selected.

Given a jQuery object that represents a set of DOM elements, the .contents() method allows us to search throughthe immediate children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .contents() and .children() methods are similar, except that the former includes text nodes as well as HTML elements in the resulting jQuery object.

The .contents() method can also be used to get the content document of an iframe, if the iframe is on the same domain as the main page.

Consider a simple <div> with a number of text nodes, each of which is separated by two line break elements (<br />):

<div class="container">
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed 
  do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
  <br /><br />
  Ut enim ad minim veniam, quis nostrud exercitation ullamco 
  laboris nisi ut aliquip ex ea commodo consequat.
  <br /> <br />
  Duis aute irure dolor in reprehenderit in voluptate velit 
  esse cillum dolore eu fugiat nulla pariatur.
</div>

We can employ the .contents() method to help convert this blob of text into three well-formed paragraphs:

$('.container').contents().filter(function() {
  return this.nodeType == 3;
})
  .wrap('<p></p>')
.end()
.filter('br')
  .remove();

This code first retrieves the contents of <div class="container"> and then filters it for text nodes, which are wrapped in paragraph tags. This is accomplished by testing the .nodeType property of the element. This DOM property holds a numeric code indicating the node's type; text nodes use the code 3. The contents are again filtered, this time for <br /> elements, and these elements are removed.

The .live() method for binding event handlers uses this property to determine the root element to use for its event delegation needs.

The value of this property is typically equal to document, as this is the default context for jQuery objects if none is supplied. The context may differ if, for example, the object was created by searching within an <iframe> or XML document.

Note that the context property may only apply to the elements originally selected by jQuery(), as it is possible for the user to add elements to the collection via methods such as .add() and these may have a different context.

The .css() method is a convenient way to get a style property from the first matched element, especially in light of the different ways browsers access most of those properties (the getComputedStyle() method in standards-based browsers versus the currentStyle and runtimeStyle properties in Internet Explorer) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the float property as styleFloat, while W3C standards-compliant browsers refer to it as cssFloat. For consistency, you can simply use "float", and jQuery will translate it to the correct value for each browser.

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css('background-color') and .css('backgroundColor'). Different browsers may return CSS color values that are logically but not textually equal, e.g., #FFF, #ffffff, and rgb(255,255,255).

Shorthand CSS properties (e.g. margin, background, border) are not supported. For example, if you want to retrieve the rendered margin, use: $(elem).css('marginTop') and $(elem).css('marginRight'), and so on.

As of jQuery 1.9, passing an array of style properties to .css() will result in an object of property-value pairs.

As with the .prop() method, the .css() method makes setting properties of elements quick and easy. This method can take either a property name and value as separate parameters, or a single object of key-value pairs.

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css({'background-color': '#ffe', 'border-left': '5px solid #ccc'}) and .css({backgroundColor: '#ffe', borderLeft: '5px solid #ccc'}). Notice that with the DOM notation, quotation marks around the property names are optional, but with CSS notation they're required due to the hyphen in the name.

When using .css() as a setter, jQuery modifies the element's style property. For example, $('#mydiv').css('color', 'green') is equivalent to document.getElementById('mydiv').style.color = 'green'. Setting the value of a style property to an empty string — e.g. $('#mydiv').css('color', '') — removes that property from an element if it has already been directly applied, whether in the HTML style attribute, through jQuery's .css() method, or through direct DOM manipulation of the style property. It does not, however, remove a style that has been applied with a CSS rule in a stylesheet or <style> element. Warning: one notable exception is that, for IE 8 and below, removing a shorthand property such as border or background> will remove that style entirely from the element, regardless of what is set in a stylesheet or <style> element.

As of jQuery 1.6, .css() accepts relative values similar to .animate(). Relative values are a string starting with += or -= to increment or decrement the current value. For example, if an element's padding-left was 10px, .css( "padding-left", "+=15" ) would result in a total padding-left of 25px.

As of jQuery 1.4, .css() allows us to pass a function as the property value:

$('div.example').css('width', function(index) {
  return index * 50;
});

This example sets the widths of the matched elements to incrementally larger values.

Note: If nothing is returned in the setter function (ie. function(index, style){}), or if undefined is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.

The .data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks.

We can set several distinct values for a single element and retrieve them later:

$("body").data("foo", 52);
$("body").data("bar", { myType: "test", count: 40 });
$("body").data({ baz: [ 1, 2, 3 ] });

$("body").data("foo"); // 52
$("body").data(); // { foo: 52, bar: { myType: "test", count: 40 }, baz: [ 1, 2, 3 ] }

In jQuery 1.4.3 setting an element's data object with .data(obj) extends the data previously stored with that element. jQuery itself uses the .data() method to save information under the names 'events' and 'handle', and also reserves any data name starting with an underscore ('_') for internal use.

Prior to jQuery 1.4.3 (starting in jQuery 1.4) the .data() method completely replaced all data, instead of just extending the data object. If you are using third-party plugins it may not be advisable to completely replace the element's data object, since plugins may have also set data.

Due to the way browsers interact with plugins and external code, the .data() method cannot be used on <object> (unless it's a Flash plugin), <applet> or <embed> elements.

The .data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can retrieve several distinct values for a single element one at a time, or as a set:

alert($('body').data('foo'));
alert($('body').data());

The above lines alert the data values that were set on the body element. If no data at all was set on that element, undefined is returned.

alert( $("body").data("foo")); //undefined
$("body").data("bar", "foobar");
alert( $("body").data("bar")); //foobar

HTML5 data-* Attributes

As of jQuery 1.4.3 HTML 5 data- attributes will be automatically pulled in to jQuery's data object. The treatment of attributes with embedded dashes was changed in jQuery 1.6 to conform to the W3C HTML5 specification.

For example, given the following HTML:

<div data-role="page" data-last-value="43" data-hidden="true" data-options='{"name":"John"}'></div>

All of the following jQuery code will work.

$("div").data("role") === "page";
$("div").data("lastValue") === 43;
$("div").data("hidden") === true;
$("div").data("options").name === "John";

Every attempt is made to convert the string to a JavaScript value (this includes booleans, numbers, objects, arrays, and null). A value is only converted to a number if doing so doesn't change the value's representation. For example, "1E02" and "100.000" are equivalent as numbers (numeric value 100) but converting them would alter their representation so they are left as strings. The string value "100" is converted to the number 100.

When the data attribute is an object (starts with '{') or array (starts with '[') then jQuery.parseJSON is used to parse the string; it must follow valid JSON syntax including quoted property names. If the value isn't parseable as a JavaScript value, it is left as a string.

To retrieve the value's attribute as a string without any attempt to convert it, use the attr() method.

The data- attributes are pulled in the first time the data property is accessed and then are no longer accessed or mutated (all data values are then stored internally in jQuery).

Calling .data() with no parameters retrieves all of the values as a JavaScript object. This object can be safely cached in a variable as long as a new object is not set with .data(obj). Using the object directly to get or set values is faster than making individual calls to .data() to get or set each value:

var mydata = $("#mydiv").data();
if ( mydata.count < 9 ) {
    mydata.count = 43;
    mydata.status = "embiggened";
}

This method is a shortcut for .on('dblclick', handler) in the first two variations, and .trigger('dblclick') in the third. The dblclick event is sent to an element when the element is double-clicked. Any HTML element can receive this event. For example, consider the HTML:

<div id="target">
  Double-click here
</div>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to any <div>:

$('#target').dblclick(function() {
  alert('Handler for .dblclick() called.');
});

Now double-clicking on this element displays the alert:

Handler for .dblclick() called.

To trigger the event manually, apply .dblclick() without an argument:

$('#other').click(function() {
  $('#target').dblclick();
});

After this code executes, (single) clicks on Trigger the handler will also alert the message.

The dblclick event is only triggered after this exact series of events:

• The mouse button is depressed while the pointer is inside the element.
• The mouse button is released while the pointer is inside the element.
• The mouse button is depressed again while the pointer is inside the element, within a time window that is system-dependent.
• The mouse button is released while the pointer is inside the element.

It is inadvisable to bind handlers to both the click and dblclick events for the same element. The sequence of events triggered varies from browser to browser, with some receiving two click events before the dblclick and others only one. Double-click sensitivity (maximum time between clicks that is detected as a double click) can vary by operating system and browser, and is often user-configurable.

The argument can be either a single function or an array of functions. When the Deferred is resolved or rejected, the alwaysCallbacks are called. Since deferred.always() returns the Deferred object, other methods of the Deferred object can be chained to this one, including additional .always() methods. When the Deferred is resolved or rejected, callbacks are executed in the order they were added, using the arguments provided to the resolve, reject, resolveWith or rejectWith method calls. For more information, see the documentation for Deferred object.

The deferred.done() method accepts one or more arguments, all of which can be either a single function or an array of functions. When the Deferred is resolved, the doneCallbacks are called. Callbacks are executed in the order they were added. Since deferred.done() returns the deferred object, other methods of the deferred object can be chained to this one, including additional .done() methods. When the Deferred is resolved, doneCallbacks are executed using the arguments provided to the resolve or resolveWith method call in the order they were added. For more information, see the documentation for Deferred object.

The deferred.fail() method accepts one or more arguments, all of which can be either a single function or an array of functions. When the Deferred is rejected, the failCallbacks are called. Callbacks are executed in the order they were added. Since deferred.fail() returns the deferred object, other methods of the deferred object can be chained to this one, including additional deferred.fail() methods. The failCallbacks are executed using the arguments provided to the deferred.reject() or deferred.rejectWith() method call in the order they were added. For more information, see the documentation for Deferred object.

As of jQuery 1.7 this API has been deprecated; please use deferred.state() instead.

Returns true if the Deferred object is in the rejected state, meaning that either deferred.reject() or deferred.rejectWith() has been called for the object and the failCallbacks have been called (or are in the process of being called).

Note that a Deferred object can be in one of three states: pending, resolved, or rejected; use deferred.isResolved() to determine whether the Deferred object is in the resolved state. These methods are primarily useful for debugging, for example to determine whether a Deferred has already been resolved even though you are inside code that intended to reject it.

This API is deprecated as of jQuery 1.7 and removed as of jQuery 1.8; please use deferred.state() instead.

Returns true if the Deferred object is in the resolved state, meaning that either deferred.resolve() or deferred.resolveWith() has been called for the object and the doneCallbacks have been called (or are in the process of being called).

Note that a Deferred object can be in one of three states: pending, resolved, or rejected; use deferred.isRejected() to determine whether the Deferred object is in the rejected state. These methods are primarily useful for debugging, for example to determine whether a Deferred has already been resolved even though you are inside code that intended to reject it.

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state or reporting status by returning a restricted Promise object through deferred.promise().

When deferred.notify is called, any progressCallbacks added by deferred.then or deferred.progress are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .notify(). Any calls to .notify() after a Deferred is resolved or rejected (or any progressCallbacks added after that) are ignored. For more information, see the documentation for Deferred object.

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state or reporting status by returning a restricted Promise object through deferred.promise().

When deferred.notifyWith is called, any progressCallbacks added by deferred.then or deferred.progress are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .notifyWith(). Any calls to .notifyWith() after a Deferred is resolved or rejected (or any progressCallbacks added after that) are ignored. For more information, see the documentation for Deferred object.

Deprecation Notice:As of jQuery 1.8, the deferred.pipe() method is deprecated. The deferred.then() method, which replaces it, should be used instead.

The deferred.pipe() method returns a new promise that filters the status and values of a deferred through a function. The doneFilter and failFilter functions filter the original deferred's resolved / rejected status and values. As of jQuery 1.7, the method also accepts a progressFilter function to filter any calls to the original deferred's notify or notifyWith methods. These filter functions can return a new value to be passed along to the piped promise's done() or fail() callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the piped promise's callbacks. If the filter function used is null, or not specified, the piped promise will be resolved or rejected with the same values as the original.

The argument can be either a single function or an array of functions. When the Deferred generates progress notifications by calling notify or notifyWith, the progressCallbacks are called. Since deferred.progress() returns the Deferred object, other methods of the Deferred object can be chained to this one. When the Deferred is resolved or rejected, progress callbacks will no longer be called, with the exception that any progressCallbacks added after the Deferred enters the resolved or rejected state are executed immediately when they are added, using the arguments that were passed to the .notify() or notifyWith() call. For more information, see the documentation for jQuery.Deferred().

The deferred.promise() method allows an asynchronous function to prevent other code from interfering with the progress or status of its internal request. The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, pipe, progress, and state), but not ones that change the state (resolve, reject, notify, resolveWith, rejectWith, and notifyWith).

If target is provided, deferred.promise() will attach the methods onto it and then return this object rather than create a new one. This can be useful to attach the Promise behavior to an object that already exists.

If you are creating a Deferred, keep a reference to the Deferred so that it can be resolved or rejected at some point. Return only the Promise object via deferred.promise() so other code can register callbacks or inspect the current state.

For more information, see the documentation for Deferred object.

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

When the Deferred is rejected, any failCallbacks added by deferred.then() or deferred.fail() are called. Callbacks are executed in the order they were added. Each callback is passed the args from the deferred.reject() call. Any failCallbacks added after the Deferred enters the rejected state are executed immediately when they are added, using the arguments that were passed to the deferred.reject() call. For more information, see the documentation for jQuery.Deferred().

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

When the Deferred is rejected, any failCallbacks added by deferred.then or deferred.fail are called. Callbacks are executed in the order they were added. Each callback is passed the args from the deferred.reject() call. Any failCallbacks added after the Deferred enters the rejected state are executed immediately when they are added, using the arguments that were passed to the .reject() call. For more information, see the documentation for Deferred object.

When the Deferred is resolved, any doneCallbacks added by deferred.then() or deferred.done() are called. Callbacks are executed in the order they were added. Each callback is passed the args from the deferred.resolve(). Any doneCallbacks added after the Deferred enters the resolved state are executed immediately when they are added, using the arguments that were passed to the deferred.resolve() call. For more information, see the documentation for jQuery.Deferred().

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

When the Deferred is resolved, any doneCallbacks added by deferred.then or deferred.done are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .resolve(). Any doneCallbacks added after the Deferred enters the resolved state are executed immediately when they are added, using the arguments that were passed to the .resolve() call. For more information, see the documentation for Deferred object.

The deferred.state() method returns a string representing the current state of the Deferred object. The Deferred object can be in one of three states:

• "pending": The Deferred object is not yet in a completed state (neither "rejected" nor "resolved").
• "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 doneCallbacks have been called (or are in the process of being 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 failCallbacks have been called (or are in the process of being called).

This method is primarily useful for debugging to determine, for example, whether a Deferred has already been resolved even though you are inside code that intended to reject it.

Prior to jQuery 1.8, the arguments could be a function or an array of functions.

For all signatures, the arguments can be null if no callback of that type is desired. Alternatively, use .done(), .fail() or .progress() to set only one type of callback without filtering status or values.

As of jQuery 1.8, the deferred.then() method returns a new promise that can filter the status and values of a deferred through a function, replacing the now-deprecated deferred.pipe() method. The doneFilter and failFilter functions filter the original deferred's resolved / rejected status and values. The progressFilter function filters any calls to the original deferred's notify or notifyWith methods. These filter functions can return a new value to be passed along to the promise's .done() or .fail() callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the promise's callbacks. If the filter function used is null, or not specified, the promise will be resolved or rejected with the same values as the original.

Callbacks are executed in the order they were added. Since deferred.then returns a Promise, other methods of the Promise object can be chained to this one, including additional .then() methods.

Added to jQuery in version 1.4, the .delay() method allows us to delay the execution of functions that follow it in the queue. It can be used with the standard effects queue or with a custom queue. Only subsequent events in a queue are delayed; for example this will not delay the no-arguments forms of .show() or .hide() which do not use the effects queue.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

Using the standard effects queue, we can, for example, set an 800-millisecond delay between the .slideUp() and .fadeIn() of <div id="foo">:

$('#foo').slideUp(300).delay(800).fadeIn(400);

When this statement is executed, the element slides up for 300 milliseconds and then pauses for 800 milliseconds before fading in for 400 milliseconds.

As of jQuery 1.7, .delegate() has been superseded by the .on() method. For earlier versions, however, it remains the most effective means to use event delegation. More information on event binding and delegation is in the .on() method. In general, these are the equivalent templates for the two methods:

// jQuery 1.4.3+
$(elements).delegate( selector, events, data, handler );
// jQuery 1.7+
$(elements).on( events, selector, data, handler );
 

For example, the following .delegate() code:

$("table").delegate("td", "click", function() {
  $(this).toggleClass("chosen");
});

is equivalent to the following code written using .on():

$("table").on("click", "td", function() {
  $(this).toggleClass("chosen");
});

To remove events attached with delegate(), see the .undelegate() method.

Passing and handling event data works the same way as it does for .on().

When .dequeue() is called, the next function on the queue is removed from the queue, and then executed. This function should in turn (directly or indirectly) cause .dequeue() to be called, so that the sequence can continue.

A descendant of an element could be a child, grandchild, great-grandchild, and so on, of that element.

The .detach() method is the same as .remove(), except that .detach() keeps all jQuery data associated with the removed elements. This method is useful when removed elements are to be reinserted into the DOM at a later time.

Any handler that has been attached with .live() can be removed with .die(). This method is analogous to calling .off() with no arguments, which is used to remove all handlers attached with .on(). See the discussions of .live() and .off() for further details.

If used without an argument, .die() removes all event handlers previously attached using .live() from the elements.

As of jQuery 1.7, use of .die() (and its complementary method, .live()) is not recommended. Instead, use .off() to remove event handlers bound with .on()

Note: In order for .die() to function correctly, the selector used with it must match exactly the selector initially used with .live().

As with other pseudo-class selectors (those that begin with a ":"), it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':disabled') is equivalent to $('*:disabled'), so $('input:disabled') or similar should be used instead.

Although their resulting selections are usually the same, the :disabled selector is subtly different from the [disabled] attribute selector; :disabled checks the boolean (true/false) value of the element's disabled property while [disabled] checks for the existence of the disabled attribute.

The :disabled selector should only be used for selecting HTML elements that support the disabled attribute (<button>, <input>, <optgroup>, <option>, <select>, and <textarea>).

The .each() method is designed to make DOM looping constructs concise and less error-prone. When called it iterates over the DOM elements that are part of the jQuery object. Each time the callback runs, it is passed the current loop iteration, beginning from 0. More importantly, the callback is fired in the context of the current DOM element, so the keyword this refers to the element.

Suppose you have a simple unordered list on the page:

<ul>
    <li>foo</li>
    <li>bar</li>
</ul>
    

You can select the list items and iterate across them:

$( "li" ).each(function( index ) {
  console.log( index + ": " + $(this).text() );
});
  

A message is thus logged for each item in the list:

0: foo
1: bar

You can stop the loop from within the callback function by returning false.

Note: most jQuery methods that return a jQuery object also loop through the set of elements in the jQuery collection — a process known as implicit iteration. When this occurs, it is often unnecessary to explicitly iterate with the .each() method:

// The .each() method is unnecessary here:
$( "li" ).each(function() {
  $(this).addClass( "foo" );
});

// Instead, you should rely on implicit iteration:
$( "li" ).addClass( "bar" );

JavaScript's getElementsByTagName() function is called to return the appropriate elements when this expression is used.

This is the inverse of :parent.

One important thing to note with :empty (and :parent) is that child elements include text nodes.

The W3C recommends that the <p> element have at least one child node, even if that child is merely text (see http://www.w3.org/TR/html401/struct/text.html#edef-P). Some other elements, on the other hand, are empty (i.e. have no children) by definition: <input>, <img>, <br>, and <hr>, for example.

This method removes not only child (and other descendant) elements, but also any text within the set of matched elements. This is because, according to the DOM specification, any string of text within an element is considered a child node of that element. Consider the following HTML:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">Goodbye</div>
</div>

We can target any element for removal:

$('.hello').empty();

This will result in a DOM structure with the Hello text deleted:

<div class="container">
  <div class="hello"></div>
  <div class="goodbye">Goodbye</div>
</div>

If we had any number of nested elements inside <div class="hello">, they would be removed, too.

To avoid memory leaks, jQuery removes other constructs such as data and event handlers from the child elements before removing the elements themselves.

If you want to remove elements without destroying their data or event handlers (so they can be re-added later), use .detach() instead.

As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':enabled') is equivalent to $('*:enabled'), so $('input:enabled') or similar should be used instead.

Although their resulting selections are usually the same, :enabled selector is subtly different from :not([disabled]); :enabled selects elements that have their boolean disabled property strictly equal to false, while :not([disabled]) selects elements that do not have a disabled attribute set (regardless of its value).

The :enabled selector should only be used for selecting HTML elements that support the disabled attribute (<button>, <input>, <optgroup>, <option>, <select>, and <textarea>).

Most of jQuery's DOM traversal methods operate on a jQuery object instance and produce a new one, matching a different set of DOM elements. When this happens, it is as if the new set of elements is pushed onto a stack that is maintained inside the object. Each successive filtering method pushes a new element set onto the stack. If we need an older element set, we can use end() to pop the sets back off of the stack.

Suppose we have a couple short lists on a page:

<ul class="first">
   <li class="foo">list item 1</li>
   <li>list item 2</li>
   <li class="bar">list item 3</li>
</ul>
<ul class="second">
   <li class="foo">list item 1</li>
   <li>list item 2</li>
   <li class="bar">list item 3</li>
</ul>

The end() method is useful primarily when exploiting jQuery's chaining properties. When not using chaining, we can usually just call up a previous object by variable name, so we don't need to manipulate the stack. With end(), though, we can string all the method calls together:

$('ul.first').find('.foo').css('background-color', 'red')
  .end().find('.bar').css('background-color', 'green');

This chain searches for items with the class foo within the first list only and turns their backgrounds red. Then end() returns the object to its state before the call to find(), so the second find() looks for '.bar' inside <ul class="first">, not just inside that list's <li class="foo">, and turns the matching elements' backgrounds green. The net result is that items 1 and 3 of the first list have a colored background, and none of the items from the second list do.

A long jQuery chain can be visualized as a structured code block, with filtering methods providing the openings of nested blocks and end() methods closing them:

$('ul.first').find('.foo')
  .css('background-color', 'red')
.end().find('.bar')
  .css('background-color', 'green')
.end();

The last end() is unnecessary, as we are discarding the jQuery object immediately thereafter. However, when the code is written in this form, the end() provides visual symmetry and a sense of completion —making the program, at least to the eyes of some developers, more readable, at the cost of a slight hit to performance as it is an additional function call.

The index-related selectors (:eq(), :lt(), :gt(), :even, :odd) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (.myclass) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.

Note that since JavaScript arrays use 0-based indexing, these selectors reflect that fact. This is why $('.myclass:eq(1)') selects the second element in the document with the class myclass, rather than the first. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

Prior to jQuery 1.8, the :eq(index) selector did not accept a negative value for index (though the .eq(index) method did).

Given a jQuery object that represents a set of DOM elements, the .eq() method constructs a new jQuery object from one element within that set. The supplied index identifies the position of this element in the set.

Consider a page with a simple list on it:

  <ul>
    <li>list item 1</li>
    <li>list item 2</li>
    <li>list item 3</li>
    <li>list item 4</li>
    <li>list item 5</li>
  </ul>

We can apply this method to the set of list items:

  $('li').eq(2).css('background-color', 'red');

The result of this call is a red background for item 3. Note that the supplied index is zero-based, and refers to the position of the element within the jQuery object, not within the DOM tree.

Providing a negative number indicates a position starting from the end of the set, rather than the beginning. For example:

  $('li').eq(-2).css('background-color', 'red');

This time list item 4 is turned red, since it is two from the end of the set.

If an element cannot be found at the specified zero-based index, the method constructs a new jQuery object with an empty set and a length property of 0.

  $('li').eq(5).css('background-color', 'red');

Here, none of the list items is turned red, since .eq(5) indicates the sixth of five list items.

This method is a shortcut for .on('error', handler).

The error event is sent to elements, such as images, that are referenced by a document and loaded by the browser. It is called if the element was not loaded correctly.

For example, consider a page with a simple image element:

<img alt="Book" id="book" />

The event handler can be bound to the image:

$('#book')
  .error(function() {
    alert('Handler for .error() called.')
  })
  .attr("src", "missing.png");
    

If the image cannot be loaded (for example, because it is not present at the supplied URL), the alert is displayed:

Handler for .error() called.

Note: A jQuery error event handler should not be attached to the window object. The browser fires the window's error event when a script error occurs. However, the window error event receives different arguments and has different return value requirements than conventional event handlers. Use window.onerror instead.

In particular, note that the 0-based indexing means that, counter-intuitively, :even selects the first element, third element, and so on within the matched set.

This property will typically be equal to the this of the function.

If you are using jQuery.proxy or another form of scope manipulation, this will be equal to whatever context you have provided, not event.currentTarget

This property is most often useful in delegated events attached by .delegate() or .on(), where the event handler is attached at an ancestor of the element being processed. It can be used, for example, to identify and remove event handlers at the delegation point.

For non-delegated event handlers attached directly to an element, event.delegateTarget will always be equal to event.currentTarget.

This property was introduced in DOM level 3.

This event method is described in the W3C DOM Level 3 specification.

This will likely be used primarily by plugin authors who wish to handle tasks differently depending on the event namespace used.

For example, clicked anchors will not take the browser to a new URL. We can use event.isDefaultPrevented() to determine if this method has been called by an event handler that was triggered by this event.

For mouseout, indicates the element being entered; for mouseover, indicates the element being exited.

This property can be useful for getting previous return values of custom events.

In addition to keeping any additional handlers on an element from being executed, this method also stops the bubbling by implicitly calling event.stopPropagation(). To simply prevent the event from bubbling to ancestor elements but allow other event handlers to execute on the same element, we can use event.stopPropagation() instead.

Use event.isImmediatePropagationStopped() to know whether this method was ever called (on that event object).

We can use event.isPropagationStopped() to determine if this method was ever called (on that event object).

This method works for custom events triggered with trigger(), as well.

Note that this will not prevent other handlers on the same element from running.

The target property can be the element that registered for the event or a descendant of it. It is often useful to compare event.target to this in order to determine if the event is being handled due to event bubbling. This property is very useful in event delegation, when events bubble.

This property can be useful for profiling event performance by getting the event.timeStamp value at two points in the code and noting the difference. To simply determine the current time inside an event handler, use (new Date).getTime() instead.

Note: Due to a bug open since 2004, this value is not populated correctly in Firefox and it is not possible to know the time the event was created in that browser.

The event.which property normalizes event.keyCode and event.charCode. It is recommended to watch event.which for keyboard key input. For more detail, read about event.charCode on the MDC.

event.which also normalizes button presses (mousedown and mouseupevents), reporting 1 for left button, 2 for middle, and 3 for right. Use event.which instead of event.button.

The .fadeIn() method animates the opacity of the matched elements. It is similar to the .fadeTo() method but that method does not unhide the element and can specify the final opacity level.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, or if the duration parameter is omitted, the default duration of 400 milliseconds is used.

We can animate any element, such as a simple image:

<div id="clickme">
      Click here
    </div>
    <img id="book" src="book.png" alt="" width="100" height="123" />
    With the element initially hidden, we can show it slowly:
    $('#clickme').click(function() {
      $('#book').fadeIn('slow', function() {
        // Animation complete
      });
    });

Easing

As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.

Callback Function

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

As of jQuery 1.6, the .promise() method can be used in conjunction with the deferred.done() method to execute a single callback for the animation as a whole when all matching elements have completed their animations ( See the example for .promise() ).

The .fadeOut() method animates the opacity of the matched elements. Once the opacity reaches 0, the display style property is set to none, so the element no longer affects the layout of the page.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, or if the duration parameter is omitted, the default duration of 400 milliseconds is used.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />

With the element initially shown, we can hide it slowly:

$('#clickme').click(function() {
  $('#book').fadeOut('slow', function() {
    // Animation complete.
  });
});

Easing

As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.

Callback Function

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

As of jQuery 1.6, the .promise() method can be used in conjunction with the deferred.done() method to execute a single callback for the animation as a whole when all matching elements have completed their animations ( See the example for .promise() ).

The .fadeTo() method animates the opacity of the matched elements. It is similar to the .fadeIn() method but that method unhides the element and always fades to 100% opacity.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, the default duration of 400 milliseconds is used. Unlike the other effect methods, .fadeTo() requires that duration be explicitly specified.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
    Click here
  </div>
  <img id="book" src="book.png" alt="" width="100" height="123" />
  With the element initially shown, we can dim it slowly:
  $('#clickme').click(function() {
    $('#book').fadeTo('slow', 0.5, function() {
      // Animation complete.
    });
  });
  

With duration set to 0, this method just changes the opacity CSS property, so .fadeTo(0, opacity) is the same as .css('opacity', opacity).

The .fadeToggle() method animates the opacity of the matched elements. When called on a visible element, the element's display style property is set to none once the opacity reaches 0, so the element no longer affects the layout of the page.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

Easing

The string representing an easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.

Callback Function

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

As of jQuery 1.6, the .promise() method can be used in conjunction with the deferred.done() method to execute a single callback for the animation as a whole when all matching elements have completed their animations ( See the example for .promise() ).

:file is equivalent to [type="file"]. As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':file') is equivalent to $('*:file'), so $('input:file') should be used instead.

Given a jQuery object that represents a set of DOM elements, the .filter() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; all elements matching the selector will be included in the result.

Consider a page with a simple list on it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
  <li>list item 6</li>
</ul>

We can apply this method to the set of list items:

  $('li').filter(':even').css('background-color', 'red');

The result of this call is a red background for items 1, 3, and 5, as they match the selector (recall that :even and :odd use 0-based indexing).

Using a Filter Function

The second form of this method allows us to filter elements against a function rather than a selector. For each element, if the function returns true (or a "truthy" value), the element will be included in the filtered set; otherwise, it will be excluded. Suppose we have a somewhat more involved HTML snippet:

<ul>
  <li><strong>list</strong> item 1 -
    one strong tag</li>
  <li><strong>list</strong> item <strong>2</strong> -
    two <span>strong tags</span></li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
  <li>list item 6</li>
</ul>

We can select the list items, then filter them based on their contents:

$('li').filter(function(index) {
  return $('strong', this).length == 1;
}).css('background-color', 'red');

This code will alter the first list item only, as it contains exactly one <strong> tag. Within the filter function, this refers to each DOM element in turn. The parameter passed to the function tells us the index of that DOM element within the set matched by the jQuery object.

We can also take advantage of the index passed through the function, which indicates the 0-based position of the element within the unfiltered set of matched elements:

$('li').filter(function(index) {
  return index % 3 == 2;
}).css('background-color', 'red');

This alteration to the code will cause the third and sixth list items to be highlighted, as it uses the modulus operator (%) to select every item with an index value that, when divided by 3, has a remainder of 2.

Given a jQuery object that represents a set of DOM elements, the .find() method allows us to search through the descendants of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .find() and .children() methods are similar, except that the latter only travels a single level down the DOM tree.

The first signature for the .find()method accepts a selector expression of the same type that we can pass to the $() function. The elements will be filtered by testing whether they match this selector.

Consider a page with a basic nested list on it:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at item II, we can find list items within it:

$('li.item-ii').find('li').css('background-color', 'red');

The result of this call is a red background on items A, B, 1, 2, 3, and C. Even though item II matches the selector expression, it is not included in the results; only descendants are considered candidates for the match.

Selector context is implemented with the .find() method; therefore, $('li.item-ii').find('li') is equivalent to $('li', 'li.item-ii').

As of jQuery 1.6, we can also filter the selection with a given jQuery collection or element. With the same nested list as above, if we start with:

var $allListElements = $('li');

And then pass this jQuery object to find:

$('li.item-ii').find( $allListElements );

This will return a jQuery collection which contains only the list elements that are descendants of item II.

Similarly, an element may also be passed to find:

var item1 = $('li.item-1')[0];
$('li.item-ii').find( item1 ).css('background-color', 'red');

The result of this call would be a red background on item 1.

While :first matches only a single element, the :first-child selector can match more than one: one for each parent. This is equivalent to :nth-child(1).

The :first pseudo-class is equivalent to :eq(0). It could also be written as :lt(1). While this matches only a single element, :first-child can match more than one: One for each parent.

Given a jQuery object that represents a set of DOM elements, the .first() method constructs a new jQuery object from the first element in that set.

Consider a page with a simple list on it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

We can apply this method to the set of list items:

$('li').first().css('background-color', 'red');

The result of this call is a red background for the first item.

As with other pseudo-class selectors (those that begin with a ":"), it is recommended to precede :focus with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':focus') is equivalent to $('*:focus'). If you are looking for the currently focused element, $( document.activeElement ) will retrieve it without having to search the whole DOM tree.

• This method is a shortcut for .on('focus', handler) in the first and second variations, and .trigger('focus') in the third.
• The focus event is sent to an element when it gains focus. This event is implicitly applicable to a limited set of elements, such as form elements (<input>, <select>, etc.) and links (<a href>). In recent browser versions, the event can be extended to include all element types by explicitly setting the element's tabindex property. An element can gain focus via keyboard commands, such as the Tab key, or by mouse clicks on the element.
• Elements with focus are usually highlighted in some way by the browser, for example with a dotted line surrounding the element. The focus is used to determine which element is the first to receive keyboard-related events.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Field 1" />
  <input type="text" value="Field 2" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the first input field:

$('#target').focus(function() {
  alert('Handler for .focus() called.');
});

Now clicking on the first field, or tabbing to it from another field, displays the alert:

Handler for .focus() called.

We can trigger the event when another element is clicked:

$('#other').click(function() {
  $('#target').focus();
});

After this code executes, clicks on Trigger the handler will also alert the message.

The focus event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the focus event will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mapping focus to the focusin event in its event delegation methods, .live() and .delegate().

This method is a shortcut for .on('focusin', handler).

The focusin event is sent to an element when it, or any element inside of it, gains focus. This is distinct from the focus event in that it supports detecting the focus event on parent elements (in other words, it supports event bubbling).

This event will likely be used together with the focusout event.

This method is a shortcut for .on('focusout', handler) when passed arguments, and .trigger('focusout') when no arguments are passed.

The focusout event is sent to an element when it, or any element inside of it, loses focus. This is distinct from the blur event in that it supports detecting the loss of focus on descendant elements (in other words, it supports event bubbling).

This event will likely be used together with the focusin event.

The .get() method grants us access to the DOM nodes underlying each jQuery object. Consider a simple unordered list:

  <ul>
    <li id="foo">foo</li>
    <li id="bar">bar</li>
  </ul>
      

With an index specified, .get(index) retrieves a single element:

console.log( $( "li" ).get( 0 ) );

Since the index is zero-based, the first list item is returned:

<li id="foo">

Each jQuery object also masquerades as an array, so we can use the array dereferencing operator to get at the list item instead:

console.log( $( "li" )[0] );

However, this syntax lacks some of the additional capabilities of .get(), such as specifying a negative index:

console.log( $( "li" ).get(-1) );

A negative index is counted from the end of the matched set, so this example returns the last item in the list:

<li id="bar">

Consider a simple unordered list:

  <ul>
    <li id="foo">foo</li>
    <li id="bar">bar</li>
  </ul>
      

Without a parameter, .get() returns an array of all of the elements:

console.log( $( "li" ).get() );

All of the matched DOM nodes are returned by this call, contained in a standard array:

[<li id="foo">, <li id="bar">]

index-related selectors

The index-related selector expressions (including this "greater than" selector) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (.myclass) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.

Note that since JavaScript arrays use 0-based indexing, these selectors reflect that fact. This is why $('.myclass:gt(1)') selects elements after the second element in the document with the class myclass, rather than after the first. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

Prior to jQuery 1.8, the :gt(index) selector did not accept a negative value for index

The expression $('div:has(p)') matches a <div> if a <p> exists anywhere among its descendants, not just as a direct child.

Given a jQuery object that represents a set of DOM elements, the .has() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against the descendants of the matching elements; the element will be included in the result if any of its descendant elements matches the selector.

Consider a page with a nested list as follows:

 <ul>
  <li>list item 1</li>
  <li>list item 2
    <ul>
      <li>list item 2-a</li>
      <li>list item 2-b</li>
    </ul>
  </li>
  <li>list item 3</li>
  <li>list item 4</li>
</ul>

We can apply this method to the set of list items as follows:

$('li').has('ul').css('background-color', 'red');

The result of this call is a red background for item 2, as it is the only <li> that has a <ul> among its descendants.

Elements may have more than one class assigned to them. In HTML, this is represented by separating the class names with a space:

<div id="mydiv" class="foo bar"></div>

The .hasClass() method will return true if the class is assigned to an element, even if other classes also are. For example, given the HTML above, the following will return true:

$('#mydiv').hasClass('foo')

As would:

$('#mydiv').hasClass('bar')

While this would return false:

$('#mydiv').hasClass('quux')

The difference between .css('height') and .height() is that the latter returns a unit-less pixel value (for example, 400) while the former returns a value with units intact (for example, 400px). The .height() method is recommended when an element's height needs to be used in a mathematical calculation.

This method is also able to find the height of the window and document.

$(window).height();   // returns height of browser viewport
$(document).height(); // returns height of HTML document

Note that .height() will always return the content height, regardless of the value of the CSS box-sizing property. As of jQuery 1.8, this may require retrieving the CSS height plus box-sizing property and then subtracting any potential border and padding on each element when the element has box-sizing: border-box. To avoid this penalty, use .css("height") rather than .height().

When calling .height(value), the value can be either a string (number and unit) or a number. If only a number is provided for the value, jQuery assumes a pixel unit. If a string is provided, however, a valid CSS measurement must be provided for the height (such as 100px, 50%, or auto). Note that in modern browsers, the CSS height property does not include padding, border, or margin.

If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.

Note that .height(value) sets the content height of the box regardless of the value of the CSS box-sizing property.

Elements can be considered hidden for several reasons:

• They have a CSS display value of none.
• They are form elements with type="hidden".
• Their width and height are explicitly set to 0.
• An ancestor element is hidden, so the element is not shown on the page.

Elements with visibility: hidden or opacity: 0 are considered to be visible, since they still consume space in the layout. During animations that hide an element, the element is considered to be visible until the end of the animation.

Elements that are not in a document are not considered to be visible; jQuery does not have a way to know if they will be visible when appended to a document since it depends on the applicable styles.

During animations to show an element, the element is considered to be visible at the start of the animation.

How :hidden is determined was changed in jQuery 1.3.2. An element is assumed to be hidden if it or any of its parents consumes no space in the document. CSS visibility isn't taken into account (therefore $(elem).css('visibility','hidden').is(':hidden') == false). The release notes outline the changes in more detail.

With no parameters, the .hide() method is the simplest way to hide an element:

$('.target').hide();
    

The matched elements will be hidden immediately, with no animation. This is roughly equivalent to calling .css('display', 'none'), except that the value of the display property is saved in jQuery's data cache so that display can later be restored to its initial value. If an element has a display value of inline, then is hidden and shown, it will once again be displayed inline.

When a duration, a plain object, or a "complete" function is provided, .hide() becomes an animation method. The .hide() method animates the width, height, and opacity of the matched elements simultaneously. When these properties reach 0, the display style property is set to none to ensure that the element no longer affects the layout of the page.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

Note that .hide() is fired immediately and will override the animation queue if no duration or a duration of 0 is specified.

As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />
With the element initially shown, we can hide it slowly:
$('#clickme').click(function() {
  $('#book').hide('slow', function() {
    alert('Animation complete.');
  });
});

The .hover() method binds handlers for both mouseenter and mouseleave events. You can use it to simply apply behavior to an element during the time the mouse is within the element.

Calling $(selector).hover(handlerIn, handlerOut) is shorthand for:

$(selector).mouseenter(handlerIn).mouseleave(handlerOut);

See the discussions for .mouseenter() and .mouseleave() for more details.

The .hover() method, when passed a single function, will execute that handler for both mouseenter and mouseleave events. This allows the user to use jQuery's various toggle methods within the handler or to respond differently within the handler depending on the event.type.

Calling $(selector).hover(handlerInOut) is shorthand for:

$(selector).on("mouseenter mouseleave", handlerInOut);

See the discussions for .mouseenter() and .mouseleave() for more details.

This method is not available on XML documents.

In an HTML document, .html() can be used to get the contents of any element. If the selector expression matches more than one element, only the first match will have its HTML content returned. Consider this code:

$('div.demo-container').html();

In order for the following <div>'s content to be retrieved, it would have to be the first one with class="demo-container" in the document:

<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
  </div>

The result would look like this:

<div class="demo-box">Demonstration Box</div>

This method uses the browser's innerHTML property. Some browsers may not return HTML that exactly replicates the HTML source in an original document. For example, Internet Explorer sometimes leaves off the quotes around attribute values if they contain only alphanumeric characters.

The .html() method is not available in XML documents.

When .html() is used to set an element's content, any content that was in that element is completely replaced by the new content. Additionally, jQuery removes other constructs such as data and event handlers from child elements before replacing those elements with the new content.

Consider the following HTML:

<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
</div>

The content of <div class="demo-container"> can be set like this:

$('div.demo-container')
  .html('<p>All new content. <em>You bet!</em></p>');

That line of code will replace everything inside <div class="demo-container">:

<div class="demo-container">
  <p>All new content. <em>You bet!</em></p>
</div>

As of jQuery 1.4, the .html() method allows the HTML content to be set by passing in a function.

$('div.demo-container').html(function() {
  var emph = '<em>' + $('p').length + ' paragraphs!</em>';
  return '<p>All new content for ' + emph + '</p>';
});

Given a document with six paragraphs, this example will set the HTML of <div class="demo-container"> to <p>All new content for <em>6 paragraphs!</em></p>.

This method uses the browser's innerHTML property. Some browsers may not generate a DOM that exactly replicates the HTML source provided. For example, Internet Explorer prior to version 8 will convert all href properties on links to absolute URLs, and Internet Explorer prior to version 9 will not correctly handle HTML5 elements without the addition of a separate compatibility layer.

Note: In Internet Explorer up to and including version 9, setting the text content of an HTML element may corrupt the text nodes of its children that are being removed from the document as a result of the operation. If you are keeping references to these DOM elements and need them to be unchanged, use .empty().html(string) instead of .html(string) so that the elements are removed from the document before the new string is assigned to the element.

For id selectors, jQuery uses the JavaScript function document.getElementById(), which is extremely efficient. When another selector is attached to the id selector, such as h2#pageTitle, jQuery performs an additional check before identifying the element as a match.

Calling jQuery() (or $()) with an id selector as its argument will return a jQuery object containing a collection of either zero or one DOM element.

Each id value must be used only once within a document. If more than one element has been assigned the same ID, queries that use that ID will only select the first matched element in the DOM. This behavior should not be relied on, however; a document with more than one element using the same ID is invalid.

If the id contains characters like periods or colons you have to escape those characters with backslashes.

:image is equivalent to [type="image"]

Return Values

If no argument is passed to the .index() method, the return value is an integer indicating the position of the first element within the jQuery object relative to its sibling elements.

If .index() is called on a collection of elements and a DOM element or jQuery object is passed in, .index() returns an integer indicating the position of the passed element relative to the original collection.

If a selector string is passed as an argument, .index() returns an integer indicating the position of the first element within the jQuery object relative to the elements matched by the selector. If the element is not found, .index() will return -1.

Detail

The complementary operation to .get(), which accepts an index and returns a DOM node, .index() can take a DOM node and returns an index. Suppose we have a simple unordered list on the page:

<ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
  <li id="baz">baz</li>
</ul>

If we retrieve one of the three list items (for example, through a DOM function or as the context to an event handler), .index() can search for this list item within the set of matched elements:

var listItem = document.getElementById('bar');
alert('Index: ' + $('li').index(listItem));
We get back the zero-based position of the list item:

Index: 1

Similarly, if we retrieve a jQuery object consisting of one of the three list items, .index() will search for that list item:

var listItem = $('#bar');
alert('Index: ' + $('li').index(listItem));

We get back the zero-based position of the list item:

Index: 1

Note that if the jQuery collection used as the .index() method's argument contains more than one element, the first element within the matched set of elements will be used.

var listItems = $('li:gt(0)');
alert('Index: ' + $('li').index(listItems));

We get back the zero-based position of the first list item within the matched set:

Index: 1

If we use a string as the .index() method's argument, it is interpreted as a jQuery selector string. The first element among the object's matched elements which also matches this selector is located.

var listItem = $('#bar');
alert('Index: ' + listItem.index('li'));

We get back the zero-based position of the list item:

Index: 1

If we omit the argument, .index() will return the position of the first element within the set of matched elements in relation to its siblings:

alert('Index: ' + $('#bar').index());

Again, we get back the zero-based position of the list item:

Index: 1

This method returns the height of the element, including top and bottom padding, in pixels.

This method is not applicable to window and document objects; for these, use .height() instead.

This method returns the width of the element, including left and right padding, in pixels.

This method is not applicable to window and document objects; for these, use .width() instead.

The :input selector basically selects all form controls.

The .after() and .insertAfter() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .after(), the selector expression preceding the method is the container after which the content is inserted. With .insertAfter(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted after the target container.

Consider the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it after several elements at once:

$('<p>Test</p>').insertAfter('.inner');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
  <p>Test</p>
</div>

We can also select an element on the page and insert it after another:

$('h2').insertAfter($('.container'));

If an element selected this way is inserted into a single location elsewhere in the DOM, it will be moved after the target (not cloned) and a new set consisting of the inserted element is returned:

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first, and that new set (the original element plus clones) is returned.

Before jQuery 1.9, the append-to-single-element case did not create a new set, but instead returned the original set which made it difficult to use the .end() method reliably when being used with an unknown number of elements.

The .before() and .insertBefore() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .before(), the selector expression preceding the method is the container before which the content is inserted. With .insertBefore(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted before the target container.

Consider the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it before several elements at once:

$('<p>Test</p>').insertBefore('.inner');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <p>Test</p>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
</div>

We can also select an element on the page and insert it before another:

$('h2').insertBefore($('.container'));

If an element selected this way is inserted into a single location elsewhere in the DOM, it will be moved before the target (not cloned) and a new set consisting of the inserted element is returned:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first, and that new set (the original element plus clones) is returned.

Before jQuery 1.9, the append-to-single-element case did not create a new set, but instead returned the original set which made it difficult to use the .end() method reliably when being used with an unknown number of elements.

Unlike other filtering methods, .is() does not create a new jQuery object. Instead, it allows you to test the contents of a jQuery object without modification. This is often useful inside callbacks, such as event handlers.

Suppose you have a list, with two of its items containing a child element:

<ul>
  <li>list <strong>item 1</strong></li>
  <li><span>list item 2</span></li>
  <li>list item 3</li>
</ul>

You can attach a click handler to the <ul> element, and then limit the code to be triggered only when a list item itself, not one of its children, is clicked:

$("ul").click(function(event) {
  var $target = $(event.target);
  if ( $target.is("li") ) {
    $target.css("background-color", "red");
  }
});

Now, when the user clicks on the word "list" in the first item or anywhere in the third item, the clicked list item will be given a red background. However, when the user clicks on item 1 in the first item or anywhere in the second item, nothing will occur, because in those cases the target of the event would be <strong> or <span>, respectively.

Prior to jQuery 1.7, in selector strings with positional selectors such as :first, :gt(), or :even, the positional filtering is done against the jQuery object passed to .is(), not against the containing document. So for the HTML shown above, an expression such as $("li:first").is("li:last") returns true, but $("li:first-child").is("li:last-child") returns false. In addition, a bug in Sizzle prevented many positional selectors from working properly. These two factors made positional selectors almost unusable in filters.

Starting with jQuery 1.7, selector strings with positional selectors apply the selector against the document, and then determine whether the first element of the current jQuery set matches any of the resulting elements. So for the HTML shown above, an expression such as $("li:first").is("li:last") returns false. Note that since positional selectors are jQuery additions and not W3C standard, we recommend using the W3C selectors whenever feasible.

Using a Function

The second form of this method evaluates expressions related to elements based on a function rather than a selector. For each element, if the function returns true, .is() returns true as well. For example, given a somewhat more involved HTML snippet:

<ul>
  <li><strong>list</strong> item 1 - one strong tag</li>
  <li><strong>list</strong> item <strong>2</strong> -
    two <span>strong tags</span></li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

You can attach a click handler to every <li> that evaluates the number of <strong> elements within the clicked <li> at that time like so:

$("li").click(function() {
  var $li = $(this),
    isWithTwo = $li.is(function() {
      return $('strong', this).length === 2;
    });
  if ( isWithTwo ) {
    $li.css("background-color", "green");
  } else {
    $li.css("background-color", "red");
  }
});

The $.Callbacks() function is internally used to provide the base functionality behind the jQuery $.ajax() and $.Deferred() components. It can be used as a similar base to define functionality for new components.

$.Callbacks() supports a number of methods including callbacks.add(),callbacks.remove(), callbacks.fire() and callbacks.disable().

Getting started

The following are two sample methods named fn1 and fn2:

function fn1( value ) {
    console.log( value );
}

function fn2( value ) {
    console.log("fn2 says: " + value);
    return false;
}

These can be added as callbacks to a $.Callbacks list and invoked as follows:

var callbacks = $.Callbacks();
callbacks.add( fn1 );

// outputs: foo!
callbacks.fire( "foo!" );

callbacks.add( fn2 );

// outputs: bar!, fn2 says: bar!
callbacks.fire( "bar!" );

The result of this is that it becomes simple to construct complex lists of callbacks where input values can be passed through to as many functions as needed with ease.

Two specific methods were being used above: .add() and .fire(). The .add() method supports adding new callbacks to the callback list, while the .fire() method executes the added functions and provides a way to pass arguments to be processed by the callbacks in the same list.

Another method supported by $.Callbacks is .remove(), which has the ability to remove a particular callback from the callback list. Here"s a practical example of .remove() being used:

var callbacks = $.Callbacks();
callbacks.add( fn1 );

// outputs: foo!
callbacks.fire( "foo!" );

callbacks.add( fn2 );

// outputs: bar!, fn2 says: bar!
callbacks.fire( "bar!" );

callbacks.remove( fn2 );

// only outputs foobar, as fn2 has been removed.
callbacks.fire( "foobar" );

Supported Flags

The flags argument is an optional argument to $.Callbacks(), structured as a list of space-separated strings that change how the callback list behaves (eg. $.Callbacks( "unique stopOnFalse" )).

Possible flags:

• once: Ensures the callback list can only be fired once (like a Deferred).
• memory: Keeps track of previous values and will call any callback added after the list has been fired right away with the latest "memorized" values (like a Deferred).
• unique: Ensures a callback can only be added once (so there are no duplicates in the list).
• stopOnFalse: Interrupts callings when a callback returns false.

By default a callback list will act like an event callback list and can be "fired" multiple times.

For examples of how flags should ideally be used, see below:

$.Callbacks( "once" ):

var callbacks = $.Callbacks( "once" );
callbacks.add( fn1 );
callbacks.fire( "foo" );
callbacks.add( fn2 );
callbacks.fire( "bar" );
callbacks.remove( fn2 );
callbacks.fire( "foobar" );

/*
output:
foo
*/

$.Callbacks( "memory" ):

var callbacks = $.Callbacks( "memory" );
callbacks.add( fn1 );
callbacks.fire( "foo" );
callbacks.add( fn2 );
callbacks.fire( "bar" );
callbacks.remove( fn2 );
callbacks.fire( "foobar" );

/*
output:
foo
fn2 says:foo
bar
fn2 says:bar
foobar
*/

$.Callbacks( "unique" ):

var callbacks = $.Callbacks( "unique" );
callbacks.add( fn1 );
callbacks.fire( "foo" );
callbacks.add( fn1 ); // repeat addition
callbacks.add( fn2 );
callbacks.fire( "bar" );
callbacks.remove( fn2 );
callbacks.fire( "foobar" );

/*
output:
foo
bar
fn2 says:bar
foobar
*/

$.Callbacks( "stopOnFalse" ):

function fn1( value ){
    console.log( value );
    return false;
}

function fn2( value ){
    fn1( "fn2 says: " + value );
    return false;
}

var callbacks = $.Callbacks( "stopOnFalse" );
callbacks.add( fn1 );
callbacks.fire( "foo" );
callbacks.add( fn2 );
callbacks.fire( "bar" );
callbacks.remove( fn2 );
callbacks.fire( "foobar" );

/*
output:
foo
bar
foobar
*/

Because $.Callbacks() supports a list of flags rather than just one, setting several flags has a cumulative effect similar to "&&". This means it's possible to combine flags to create callback lists that, say, both are unique and ensure if list was already fired, adding more callbacks will have it called with the latest fired value (i.e. $.Callbacks("unique memory")).

$.Callbacks( 'unique memory' ):

function fn1( value ) {
    console.log( value );
    return false;
}

function fn2( value ) {
    fn1( "fn2 says: " + value );
    return false;
}

var callbacks = $.Callbacks( "unique memory" );
callbacks.add( fn1 );
callbacks.fire( "foo" );
callbacks.add( fn1 ); // repeat addition
callbacks.add( fn2 );
callbacks.fire( "bar" );
callbacks.add( fn2 );
callbacks.fire( "baz" );
callbacks.remove( fn2 );
callbacks.fire( "foobar" );

/*
output:
foo
fn2 says:foo
bar
fn2 says:bar
baz
fn2 says:baz
foobar
*/

Flag combinations with $.Callbacks() are internally in jQuery for the .done() and .fail() functions on a Deferred — both of which use $.Callbacks('memory once').

The methods of $.Callbacks can also be detached, should there be a need to define short-hand versions for convenience:

var callbacks = $.Callbacks(),
    add = callbacks.add,
    remove = callbacks.remove,
    fire = callbacks.fire;

add( fn1 );
fire( "hello world" );
remove( fn1 );

$.Callbacks, $.Deferred and Pub/Sub

The general idea behind pub/sub (Publish/Subscribe, or, the Observer pattern) is the promotion of loose coupling in applications. Rather than single objects calling on the methods of other objects, an object instead subscribes to a specific task or activity of another object and is notified when it occurs. Observers are also called Subscribers, and we refer to the object being observed as the Publisher (or the subject). Publishers notify subscribers when events occur.

To demonstrate the component-creation capabilities of $.Callbacks(), it's possible to implement a Pub/Sub system using only callback lists. Using $.Callbacks as a topics queue, a system for publishing and subscribing to topics can be implemented as follows:

var topics = {};

jQuery.Topic = function( id ) {
    var callbacks,
        method,
        topic = id && topics[ id ];

    if ( !topic ) {
        callbacks = jQuery.Callbacks();
        topic = {
            publish: callbacks.fire,
            subscribe: callbacks.add,
            unsubscribe: callbacks.remove
        };
        if ( id ) {
            topics[ id ] = topic;
        }
    }
    return topic;
};

This can then be used by parts of your application to publish and subscribe to events of interest quite easily:

// Subscribers
$.Topic( "mailArrived" ).subscribe( fn1 );
$.Topic( "mailArrived" ).subscribe( fn2 );
$.Topic( "mailSent" ).subscribe( fn1 );

// Publisher
$.Topic( "mailArrived" ).publish( "hello world!" );
$.Topic( "mailSent" ).publish( "woo! mail!" );

// Here, "hello world!" gets pushed to fn1 and fn2
// when the "mailArrived" notification is published
// with "woo! mail!" also being pushed to fn1 when
// the "mailSent" notification is published.

/*
output:
hello world!
fn2 says: hello world!
woo! mail!
*/

While this is useful, the implementation can be taken further. Using $.Deferreds, it's possible to ensure publishers only publish notifications for subscribers once particular tasks have been completed (resolved). See the below code sample for some further comments on how this could be used in practice:

// subscribe to the mailArrived notification
$.Topic( "mailArrived" ).subscribe( fn1 );

// create a new instance of Deferreds
var dfd = $.Deferred();

// define a new topic (without directly publishing)
var topic = $.Topic( "mailArrived" );

// when the deferred has been resolved, publish a
// notification to subscribers
dfd.done( topic.publish );

// Here the Deferred is being resolved with a message
// that will be passed back to subscribers. It's possible to
// easily integrate this into a more complex routine
// (eg. waiting on an ajax call to complete) so that
// messages are only published once the task has actually
// finished.
dfd.resolve( "it's been published!" );

The $.ajax() function underlies all Ajax requests sent by jQuery. It is often unnecessary to directly call this function, as several higher-level alternatives like $.get() and .load() are available and are easier to use. If less common options are required, though, $.ajax() can be used more flexibly.

At its simplest, the $.ajax() function can be called with no arguments:

$.ajax();

Note: Default settings can be set globally by using the $.ajaxSetup() function.

This example, using no options, loads the contents of the current page, but does nothing with the result. To use the result, you can implement one of the callback functions.

The jqXHR Object

The jQuery XMLHttpRequest (jqXHR) object returned by $.ajax() as of jQuery 1.5 is a superset of the browser's native XMLHttpRequest object. For example, it contains responseText and responseXML properties, as well as a getResponseHeader() method. When the transport mechanism is something other than XMLHttpRequest (for example, a script tag for a JSONP request) the jqXHR object simulates native XHR functionality where possible.

As of jQuery 1.5.1, the jqXHR object also contains the overrideMimeType() method (it was available in jQuery 1.4.x, as well, but was temporarily removed in jQuery 1.5). The .overrideMimeType() method may be used in the beforeSend() callback function, for example, to modify the response content-type header:

$.ajax({
  url: "http://fiddle.jshell.net/favicon.png",
  beforeSend: function ( xhr ) {
    xhr.overrideMimeType("text/plain; charset=x-user-defined");
  }
}).done(function ( data ) {
  if( console && console.log ) {
    console.log("Sample of data:", data.slice(0, 100));
  }
});

The jqXHR objects returned by $.ajax() as of jQuery 1.5 implement the Promise interface, giving them all the properties, methods, and behavior of a Promise (see Deferred object for more information). These methods take one or more function arguments that are called when the $.ajax() request terminates. This allows you to assign multiple callbacks on a single request, and even to assign callbacks after the request may have completed. (If the request is already complete, the callback is fired immediately.) Available Promise methods of the jqXHR object include:

• jqXHR.done(function(data, textStatus, jqXHR) {});

  An alternative construct to the success callback option, the .done() method replaces the deprecated jqXHR.success() method. Refer to deferred.done() for implementation details.

• jqXHR.fail(function(jqXHR, textStatus, errorThrown) {});

  An alternative construct to the error callback option, the .fail() method replaces the deprecated .error() method. Refer to deferred.fail() for implementation details.

• jqXHR.always(function(data|jqXHR, textStatus, jqXHR|errorThrown) { });

  An alternative construct to the complete callback option, the .always() method replaces the deprecated .complete() method.

  In response to a successful request, the function's arguments are the same as those of .done(): data, textStatus, and the jqXHR object. For failed requests the arguments are the same as those of .fail(): the jqXHR object, textStatus, and errorThrown. Refer to deferred.always() for implementation details.

• jqXHR.then(function(data, textStatus, jqXHR) {}, function(jqXHR, textStatus, errorThrown) {});

  Incorporates the functionality of the .done() and .fail() methods, allowing (as of jQuery 1.8) the underlying Promise to be manipulated. Refer to deferred.then() for implementation details.

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.ajax( "example.php" )
    .done(function() { alert("success"); })
    .fail(function() { alert("error"); })
    .always(function() { alert("complete"); });

// perform other work here ...

// Set another completion function for the request above
jqxhr.always(function() { alert("second complete"); });

The this reference within all callbacks is the object in the context option passed to $.ajax in the settings; if context is not specified, this is a reference to the Ajax settings themselves.

For backward compatibility with XMLHttpRequest, a jqXHR object will expose the following properties and methods:

• readyState
• status
• statusText
• responseXML and/or responseText when the underlying request responded with xml and/or text, respectively
• setRequestHeader(name, value) which departs from the standard by replacing the old value with the new one rather than concatenating the new value to the old one
• getAllResponseHeaders()
• getResponseHeader()
• statusCode()
• abort()

No onreadystatechange mechanism is provided, however, since done, fail, always, and statusCode cover all conceivable requirements.

Callback Function Queues

The beforeSend, error, dataFilter, success and complete options all accept callback functions that are invoked at the appropriate times.

As of jQuery 1.5, the fail and done, and, as of jQuery 1.6, always callback hooks are first-in, first-out managed queues, allowing for more than one callback for each hook. See Deferred object methods, which are implemented internally for these $.ajax() callback hooks.

The callback hooks provided by $.ajax() are as follows:

1. beforeSend callback option is invoked; it receives the jqXHR object and the settings object as parameters.
2. error callback option is invoked, if the request fails. It receives the jqXHR, a string indicating the error type, and an exception object if applicable. Some built-in errors will provide a string as the exception object: "abort", "timeout", "No Transport".
3. dataFilter callback option is invoked immediately upon successful receipt of response data. It receives the returned data and the value of dataType, and must return the (possibly altered) data to pass on to success.
4. success callback option is invoked, if the request succeeds. It receives the returned data, a string containing the success code, and the jqXHR object.
5. Promise callbacks — .done(), .fail(), .always(), and .then() — are invoked, in the order they are registered.
6. complete callback option fires, when the request finishes, whether in failure or success. It receives the jqXHR object, as well as a string containing the success or error code.

Data Types

The $.ajax() function relies on the server to provide information about the retrieved data. If the server reports the return data as XML, the result can be traversed using normal XML methods or jQuery's selectors. If another type is detected, such as HTML in the example above, the data is treated as text.

Different data handling can be achieved by using the dataType option. Besides plain xml, the dataType can be html, json, jsonp, script, or text.

The text and xml types return the data with no processing. The data is simply passed on to the success handler, either through the responseText or responseXML property of the jqXHR object, respectively.

Note: We must ensure that the MIME type reported by the web server matches our choice of dataType. In particular, XML must be declared by the server as text/xml or application/xml for consistent results.

If html is specified, any embedded JavaScript inside the retrieved data is executed before the HTML is returned as a string. Similarly, script will execute the JavaScript that is pulled back from the server, then return nothing.

The json type parses the fetched data file as a JavaScript object and returns the constructed object as the result data. To do so, it uses jQuery.parseJSON() when the browser supports it; otherwise it uses a Function constructor. Malformed JSON data will throw a parse error (see json.org for more information). JSON data is convenient for communicating structured data in a way that is concise and easy for JavaScript to parse. If the fetched data file exists on a remote server, specify the jsonp type instead.

The jsonp type appends a query string parameter of callback=? to the URL. The server should prepend the JSON data with the callback name to form a valid JSONP response. We can specify a parameter name other than callback with the jsonp option to $.ajax().

Note: JSONP is an extension of the JSON format, requiring some server-side code to detect and handle the query string parameter. More information about it can be found in the original post detailing its use.

When data is retrieved from remote servers (which is only possible using the script or jsonp data types), the error callbacks and global events will never be fired.

Sending Data to the Server

By default, Ajax requests are sent using the GET HTTP method. If the POST method is required, the method can be specified by setting a value for the type option. This option affects how the contents of the data option are sent to the server. POST data will always be transmitted to the server using UTF-8 charset, per the W3C XMLHTTPRequest standard.

The data option can contain either a query string of the form key1=value1&key2=value2, or an object of the form {key1: 'value1', key2: 'value2'}. If the latter form is used, the data is converted into a query string using jQuery.param() before it is sent. This processing can be circumvented by setting processData to false. The processing might be undesirable if you wish to send an XML object to the server; in this case, change the contentType option from application/x-www-form-urlencoded to a more appropriate MIME type.

Advanced Options

The global option prevents handlers registered using .ajaxSend(), .ajaxError(), and similar methods from firing when this request would trigger them. This can be useful to, for example, suppress a loading indicator that was implemented with .ajaxSend() if the requests are frequent and brief. With cross-domain script and JSONP requests, the global option is automatically set to false. See the descriptions of these methods below for more details. See the descriptions of these methods below for more details.

If the server performs HTTP authentication before providing a response, the user name and password pair can be sent via the username and password options.

Ajax requests are time-limited, so errors can be caught and handled to provide a better user experience. Request timeouts are usually either left at their default or set as a global default using $.ajaxSetup() rather than being overridden for specific requests with the timeout option.

By default, requests are always issued, but the browser may serve results out of its cache. To disallow use of the cached results, set cache to false. To cause the request to report failure if the asset has not been modified since the last request, set ifModified to true.

The scriptCharset allows the character set to be explicitly specified for requests that use a <script> tag (that is, a type of script or jsonp). This is useful if the script and host page have differing character sets.

The first letter in Ajax stands for "asynchronous," meaning that the operation occurs in parallel and the order of completion is not guaranteed. The async option to $.ajax() defaults to true, indicating that code execution can continue after the request is made. Setting this option to false (and thus making the call no longer asynchronous) is strongly discouraged, as it can cause the browser to become unresponsive.

The $.ajax() function returns the XMLHttpRequest object that it creates. Normally jQuery handles the creation of this object internally, but a custom function for manufacturing one can be specified using the xhr option. The returned object can generally be discarded, but does provide a lower-level interface for observing and manipulating the request. In particular, calling .abort() on the object will halt the request before it completes.

At present, due to a bug in Firefox where .getAllResponseHeaders() returns the empty string although .getResponseHeader('Content-Type') returns a non-empty string, automatically decoding JSON CORS responses in Firefox with jQuery is not supported.

A workaround to this is possible by overriding jQuery.ajaxSettings.xhr as follows:

(function () {
  var _super = jQuery.ajaxSettings.xhr,
    xhrCorsHeaders = [ "Cache-Control", "Content-Language", "Content-Type", "Expires", "Last-Modified", "Pragma" ];

  jQuery.ajaxSettings.xhr = function () {
    var xhr = _super(),
      getAllResponseHeaders = xhr.getAllResponseHeaders;

    xhr.getAllResponseHeaders = function () {
      var allHeaders = "";
      try {
        allHeaders = getAllResponseHeaders.apply( xhr );
        if ( allHeaders ) {
          return allHeaders;
        }
      } catch ( e ) {
      }

      $.each( xhrCorsHeaders, function ( i, headerName ) {
        if ( xhr.getResponseHeader( headerName ) ) {
          allHeaders += headerName + ": " + xhr.getResponseHeader( headerName ) + "\n";
        }
      });
      return allHeaders;
    };

    return xhr;
  };
})();

Extending Ajax

As of jQuery 1.5, jQuery's Ajax implementation includes prefilters, transports, and converters that allow you to extend Ajax with a great deal of flexibility.

Using Converters

$.ajax() converters support mapping data types to other data types. If, however, you want to map a custom data type to a known type (e.g json), you must add a correspondance between the response Content-Type and the actual data type using the contents option:

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "mycustomtype json": function ( result ) {
      // do stuff
      return newresult;
    }
  }
});

This extra object is necessary because the response Content-Types and data types never have a strict one-to-one correspondance (hence the regular expression).

To convert from a supported type (e.g text, json) to a custom data type and back again, use another pass-through converter:

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "text mycustomtype": true,
    "mycustomtype json": function ( result ) {
      // do stuff
      return newresult;
    }
  }
});

The above now allows passing from text to mycustomtype and then mycustomtype to json.

A typical prefilter registration using $.ajaxPrefilter() looks like this:

$.ajaxPrefilter( function( options, originalOptions, jqXHR ) {
  // Modify options, control originalOptions, store jqXHR, etc
});

where:

• options are the request options
• originalOptions are the options as provided to the ajax method, unmodified and, thus, without defaults from ajaxSettings
• jqXHR is the jqXHR object of the request

Prefilters are a perfect fit when custom options need to be handled. Given the following code, for example, a call to $.ajax() would automatically abort a request to the same URL if the custom abortOnRetry option is set to true:

var currentRequests = {};

$.ajaxPrefilter(function( options, originalOptions, jqXHR ) {
  if ( options.abortOnRetry ) {
    if ( currentRequests[ options.url ] ) {
      currentRequests[ options.url ].abort();
    }
    currentRequests[ options.url ] = jqXHR;
  }
});

Prefilters can also be used to modify existing options. For example, the following proxies cross-domain requests through http://mydomain.net/proxy/:

$.ajaxPrefilter( function( options ) {
  if ( options.crossDomain ) {
    options.url = "http://mydomain.net/proxy/" + encodeURIComponent( options.url );
    options.crossDomain = false;
  }
});

If the optional dataTypes argument is supplied, the prefilter will be only be applied to requests with the indicated dataTypes. For example, the following only applies the given prefilter to JSON and script requests:

$.ajaxPrefilter( "json script", function( options, originalOptions, jqXHR ) {
  // Modify options, control originalOptions, store jqXHR, etc
});

The $.ajaxPrefilter() method can also redirect a request to another dataType by returning that dataType. For example, the following sets a request as "script" if the URL has some specific properties defined in a custom isActuallyScript() function:

$.ajaxPrefilter(function( options ) {
  if ( isActuallyScript( options.url ) ) {
    return "script";
  }
});

This would ensure not only that the request is considered "script" but also that all the prefilters specifically attached to the script dataType would be applied to it.

For details on the settings available for $.ajaxSetup(), see $.ajax().

All subsequent Ajax calls using any function will use the new settings, unless overridden by the individual calls, until the next invocation of $.ajaxSetup().

Note: The settings specified here will affect all calls to $.ajax or AJAX-based derivatives such as $.get(). This can cause undesirable behavior since other callers (for example, plugins) may be expecting the normal default settings. For that reason we strongly recommend against using this API. Instead, set the options explicitly in the call or define a simple plugin to do so.

For example, the following sets a default for the url parameter before pinging the server repeatedly:

$.ajaxSetup({
  url: 'ping.php'
});

Now each time an Ajax request is made, the "ping.php" URL will be used automatically:

$.ajax({
  // url not set here; uses ping.php
  data: {'name': 'Dan'}
});

A transport is an object that provides two methods, send and abort, that are used internally by $.ajax() to issue requests. A transport is the most advanced way to enhance $.ajax() and should be used only as a last resort when prefilters and converters are insufficient.

Since each request requires its own transport object instance, transports cannot be registered directly. Therefore, you should provide a function that returns a transport instead.

Transports factories are registered using $.ajaxTransport(). A typical registration looks like this:

$.ajaxTransport( function( options, originalOptions, jqXHR ) {
  if( /* transportCanHandleRequest */ ) {
    return {
      send: function( headers, completeCallback ) {
        /* send code */
      },
      abort: function() {
        /* abort code */
      }
    };
  }
});

where:

• options are the request options
• originalOptions are the options as provided to the ajax method, unmodified and, thus, without defaults from ajaxSettings
• jqXHR is the jqXHR object of the request
• headers is an object of (key-value) request headers that the transport can transmit if it supports it
• completeCallback is the callback used to notify ajax of the completion of the request

completeCallback has the following signature:

function( status, statusText, responses, headers ) {}

where:

• status is the HTTP status code of the response, like 200 for a typical success, or 404 for when the resource is not found.
• statusText is the statusText of the response.
• responses (Optional) is An object containing dataType/value that contains the response in all the formats the transport could provide (for instance, a native XMLHttpRequest object would set reponses to { xml: XMLData, text: textData } for a response that is an XML document)
• headers (Optional) is a string containing all the response headers if the transport has access to them (akin to what XMLHttpRequest.getAllResponseHeaders() would provide).

Just like prefilters, a transport's factory function can be attached to a specific dataType:

$.ajaxTransport( "script", function( options, originalOptions, jqXHR ) {
    /* Will only be called for script requests */
});

The following example shows how a minimal image transport could be implemented:

$.ajaxTransport( "image", function( s ) {

  if ( s.type === "GET" && s.async ) {

    var image;

    return {

      send: function( _ , callback ) {

        image = new Image();

        function done( status ) {
          if ( image ) {
            var statusText = ( status == 200 ) ? "success" : "error",
            tmp = image;
            image = image.onreadystatechange = image.onerror = image.onload = null;
            callback( status, statusText, { image: tmp } );
          }
        }

        image.onreadystatechange = image.onload = function() {
          done( 200 );
        };
        image.onerror = function() {
          done( 404 );
        };

        image.src = s.url;
      },

      abort: function() {
        if ( image ) {
          image = image.onreadystatechange = image.onerror = image.onload = null;
        }
      }
    };
  }
});

Handling Custom Data Types

The jQuery Ajax implementation comes with a set of standard dataTypes, such as text, json, xml, and html.

Use the converters option in $.ajaxSetup() to augment or modify the data type conversion strategies used by $.ajax().

The unminified jQuery source itself includes a list of default converters, which effectively illustrates how they can be used:

// List of data converters
// 1) key format is "source_type destination_type"
//    (a single space in-between)
// 2) the catchall symbol "*" can be used for source_type
converters: {

  // Convert anything to text
  "* text": window.String,

  // Text to html (true = no transformation)
  "text html": true,

  // Evaluate text as a json expression
  "text json": jQuery.parseJSON,

  // Parse text as xml
  "text xml": jQuery.parseXML
}

When you specify a converters option globally in $.ajaxSetup() or per call in $.ajax(), the object will map onto the default converters, overwriting those you specify and leaving the others intact.

For example, the jQuery source uses $.ajaxSetup() to add a converter for "text script":

jQuery.ajaxSetup({
  accepts: {
    script: "text/javascript, application/javascript"
  },
  contents: {
    script: /javascript/
  },
  converters: {
    "text script": jQuery.globalEval
  }
});

The $.browser property provides information about the web browser that is accessing the page, as reported by the browser itself. It contains flags for each of the four most prevalent browser classes (Internet Explorer, Mozilla, Webkit, and Opera) as well as version information.

Available flags are:

• webkit (as of jQuery 1.4)
• safari (deprecated)
• opera
• msie
• mozilla

This property is available immediately. It is therefore safe to use it to determine whether or not to call $(document).ready(). The $.browser property is deprecated in jQuery 1.3, and its functionality may be moved to a team-supported plugin in a future release of jQuery.

Because $.browser uses navigator.userAgent to determine the platform, it is vulnerable to spoofing by the user or misrepresentation by the browser itself. It is always best to avoid browser-specific code entirely where possible. The $.support property is available for detection of support for particular features rather than relying on $.browser.

Here are some typical results:

• Internet Explorer: 6.0, 7.0, 8.0
• Mozilla/Firefox/Flock/Camino: 1.7.12, 1.8.1.3, 1.9
• Opera: 10.06, 11.01
• Safari/Webkit: 312.8, 418.9

Note that IE8 claims to be 7 in Compatibility View.

The $.contains() method returns true if the DOM element provided by the second argument is a descendant of the DOM element provided by the first argument, whether it is a direct child or nested more deeply. Otherwise, it returns false. Only element nodes are supported; if the second argument is a text or comment node, $.contains() will return false.

The $.cssHooks object provides a way to define functions for getting and setting particular CSS values. It can also be used to create new cssHooks for normalizing CSS3 features such as box shadows and gradients.

For example, some versions of Webkit-based browsers require -webkit-border-radius to set the border-radius on an element, while earlier Firefox versions require -moz-border-radius. A css hook can normalize these vendor-prefixed properties to let .css() accept a single, standard property name (border-radius, or with DOM property syntax, borderRadius).

In addition to providing fine-grained control over how specific style properties are handled, $.cssHooks also extends the set of properties available to the .animate() method.

Defining a new css hook is straight-forward. The skeleton template below can serve as a guide to creating your own.

      (function($) {
  // first, check to see if cssHooks are supported
  if ( !$.cssHooks ) {
    // if not, output an error message
    throw("jQuery 1.4.3 or above is required for this plugin to work");
    return;
  }

  // Wrap in a document ready call, because jQuery writes
  // cssHooks at this time and will blow away your functions
  // if they exist.
  $(function () {
    $.cssHooks["someCSSProp"] = {
      get: function( elem, computed, extra ) {
        // handle getting the CSS property
      },
      set: function( elem, value ) {
        // handle setting the CSS value
      }
    };
  });
})(jQuery);

    

Feature Testing

Before normalizing a vendor-specific CSS property, first determine whether the browser supports the standard property or a vendor-prefixed variation. For example, to check for support of the border-radius property, see if any variation is a member of a temporary element's style object.

      (function($) {
  function styleSupport( prop ) {
    var vendorProp, supportedProp,

        // capitalize first character of the prop to test vendor prefix
        capProp = prop.charAt(0).toUpperCase() + prop.slice(1),
        prefixes = [ "Moz", "Webkit", "O", "ms" ],
        div = document.createElement( "div" );

    if ( prop in div.style ) {

      // browser supports standard CSS property name
      supportedProp = prop;
    } else {

      // otherwise test support for vendor-prefixed property names
      for ( var i = 0; i < prefixes.length; i++ ) {
        vendorProp = prefixes[i] + capProp;
        if ( vendorProp in div.style ) {
          supportedProp = vendorProp;
          break;
        }
      }
    }

    // avoid memory leak in IE
    div = null;

    // add property to $.support so it can be accessed elsewhere
    $.support[ prop ] = supportedProp;

    return supportedProp;
  }

  // call the function, e.g. testing for "border-radius" support:
  styleSupport( "borderRadius" );
})(jQuery);

    

Defining a complete css hook

To define a complete css hook, combine the support test with a filled-out version of the skeleton template provided in the first example:

      (function($) {
  if ( !$.cssHooks ) {
    throw("jQuery 1.4.3+ is needed for this plugin to work");
    return;
  }

  function styleSupport( prop ) {
    var vendorProp, supportedProp,
        capProp = prop.charAt(0).toUpperCase() + prop.slice(1),
        prefixes = [ "Moz", "Webkit", "O", "ms" ],
        div = document.createElement( "div" );

    if ( prop in div.style ) {
      supportedProp = prop;
    } else {
      for ( var i = 0; i < prefixes.length; i++ ) {
        vendorProp = prefixes[i] + capProp;
        if ( vendorProp in div.style ) {
          supportedProp = vendorProp;
          break;
        }
      }
    }

    div = null;
    $.support[ prop ] = supportedProp
    return supportedProp;
  }

  var borderRadius = styleSupport( "borderRadius" );

  // Set cssHooks only for browsers that
  // support a vendor-prefixed border radius
  if ( borderRadius && borderRadius !== "borderRadius" ) {
    $.cssHooks.borderRadius = {
      get: function( elem, computed, extra ) {
        return $.css( elem, borderRadius );
      },
      set: function( elem, value) {
        elem.style[ borderRadius ] = value;
      }
    };
  }
})(jQuery);

    

You can then set the border radius in a supported browser using either the DOM (camelCased) style or the CSS (hyphenated) style:

      
$("#element").css("borderRadius", "10px");
$("#another").css("border-radius", "20px");

    

If the browser lacks support for any form of the CSS property, vendor-prefixed or not, the style is not applied to the element. However, if the browser supports a proprietary alternative, it can be applied to the cssHooks instead.

      
 (function($) {
  // feature test for support of a CSS property
  // and a proprietary alternative
  // ...


 if ( $.support.someCSSProp && $.support.someCSSProp !== "someCSSProp" ) {

    // Set cssHooks for browsers that
    // support only a vendor-prefixed someCSSProp
    $.cssHooks.someCSSProp = {
      get: function( elem, computed, extra ) {
        return $.css( elem, $.support.someCSSProp );
      },
      set: function( elem, value) {
        elem.style[ $.support.someCSSProp ] = value;
      }
    };
  } else if ( supportsProprietaryAlternative ) {
    $.cssHooks.someCSSProp = {
      get: function( elem, computed, extra ) {
        // Handle crazy conversion from the proprietary alternative
      },
      set: function( elem, value ) {
        // Handle crazy conversion to the proprietary alternative
      }
    }
  }

})(jQuery);

    

Special units

By default, jQuery adds a "px" unit to the values passed to the .css() method. This behavior can be prevented by adding the property to the jQuery.cssNumber object

      $.cssNumber["someCSSProp"] = true;
    

Animating with cssHooks

A css hook can also hook into jQuery's animation mechanism by adding a property to the jQuery.fx.step object:

      $.fx.step["someCSSProp"] = function(fx){
  $.cssHooks["someCSSProp"].set( fx.elem, fx.now + fx.unit );
};

    

Note that this works best for simple numeric-value animations. More custom code may be required depending on the CSS property, the type of value it returns, and the animation's complexity.

Note: This is a low-level method; a more convenient .data() is also available.

The jQuery.data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore free from memory leaks. jQuery ensures that the data is removed when DOM elements are removed via jQuery methods, and when the user leaves the page. We can set several distinct values for a single element and retrieve them later:

jQuery.data(document.body, 'foo', 52);
jQuery.data(document.body, 'bar', 'test');

Note: this method currently does not provide cross-platform support for setting data on XML documents, as Internet Explorer does not allow data to be attached via expando properties.

Note: This is a low-level method; a more convenient .data() is also available.

Regarding HTML5 data-* attributes: This low-level method does NOT retrieve the data-* attributes unless the more convenient .data() method has already retrieved them.

The jQuery.data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can retrieve several distinct values for a single element one at a time, or as a set:

alert(jQuery.data( document.body, 'foo' ));
alert(jQuery.data( document.body ));

The above lines alert the data values that were set on the body element. If nothing was set on that element, an empty string is returned.

Calling jQuery.data(element) retrieves all of the element's associated values as a JavaScript object. Note that jQuery itself uses this method to store data for internal use, such as event handlers, so do not assume that it contains only data that your own code has stored.

Note: this method currently does not provide cross-platform support for setting data on XML documents, as Internet Explorer does not allow data to be attached via expando properties.

Note: This is a low-level method, you should probably use .dequeue() instead.

When jQuery.dequeue() is called, the next function on the queue is removed from the queue, and then executed. This function should in turn (directly or indirectly) cause jQuery.dequeue() to be called, so that the sequence can continue.

The $.each() function is not the same as $(selector).each(), which is used to iterate, exclusively, over a jQuery object. The $.each() function can be used to iterate over any collection, whether it is an object or an array. In the case of an array, the callback is passed an array index and a corresponding array value each time. (The value can also be accessed through the this keyword, but Javascript will always wrap the this value as an Object even if it is a simple string or number value.) The method returns its first argument, the object that was iterated.

$.each([52, 97], function(index, value) {
  alert(index + ': ' + value);
});

This produces two messages:

0: 52
1: 97

If an object is used as the collection, the callback is passed a key-value pair each time:

var obj = {
  "flammable": "inflammable",
  "duh": "no duh"
};
$.each( obj, function( key, value ) {
  alert( key + ": " + value );
});

Once again, this produces two messages:

flammable: inflammable
duh: no duh

We can break the $.each() loop at a particular iteration by making the callback function return false. Returning non-false is the same as a continue statement in a for loop; it will skip immediately to the next iteration.

This method exists primarily for plugin developers who wish to override it and provide a better display (or more information) for the error messages.

When two or more object arguments are supplied to $.extend(), properties from all of the objects are added to the target object. Arguments that are null or undefined are ignored.

If only one argument is supplied to $.extend(), this means the target argument was omitted. In this case, the jQuery object itself is assumed to be the target. By doing this, you can add new functions to the jQuery namespace. This can be useful for plugin authors wishing to add new methods to JQuery.

Keep in mind that the target object (first argument) will be modified, and will also be returned from $.extend(). If, however, you want to preserve both of the original objects, you can do so by passing an empty object as the target:

var object = $.extend({}, object1, object2);

The merge performed by $.extend() is not recursive by default; if a property of the first object is itself an object or array, it will be completely overwritten by a property with the same key in the second or subsequent object. The values are not merged. This can be seen in the example below by examining the value of banana. However, by passing true for the first function argument, objects will be recursively merged.

Warning: Passing false for the first argument is not supported.

Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over. Properties that are an object constructed via new MyCustomObject(args), or built-in JavaScript types such as Date or RegExp, are not re-constructed and will appear as plain Objects in the resulting object or array.

On a deep extend, Object and Array are extended, but object wrappers on primitive types such as String, Boolean, and Number are not.

For needs that fall outside of this behavior, write a custom extend method instead.

This property can be manipulated to adjust the number of frames per second at which animations will run. The default is 13 milliseconds. Making this a lower number could make the animations run smoother in faster browsers (such as Chrome) but there may be performance and CPU implications of doing so.

Since jQuery uses one global interval, no animation should be running or all animations should stop for the change of this property to take effect.

Note:jQuery.fx.interval currently has no effect in browsers that support the requestAnimationFrame property, such as Google Chrome 11. This behavior is subject to change in a future release.

When this property is set to true, all animation methods will immediately set elements to their final state when called, rather than displaying an effect. This may be desirable for a couple reasons:

• jQuery is being used on a low-resource device.
• Users are encountering accessibility problems with the animations (see the article Turn Off Animation for more information).

Animations can be turned back on by setting the property to false.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  url: url,
  data: data,
  success: success,
  dataType: dataType
});

The success callback function is passed the returned data, which will be an XML root element, text string, JavaScript file, or JSON object, depending on the MIME type of the response. It is also passed the text status of the response.

As of jQuery 1.5, the success callback function is also passed a "jqXHR" object (in jQuery 1.4, it was passed the XMLHttpRequest object). However, since JSONP and cross-domain GET requests do not use XHR, in those cases the jqXHR and textStatus parameters passed to the success callback are undefined.

Most implementations will specify a success handler:

$.get('ajax/test.html', function(data) {
  $('.result').html(data);
  alert('Load was performed.');
});

This example fetches the requested HTML snippet and inserts it on the page.

The jqXHR Object

As of jQuery 1.5, all of jQuery's Ajax methods return a superset of the XMLHTTPRequest object. This jQuery XHR object, or "jqXHR," returned by $.get() implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see Deferred object for more information). The jqXHR.done() (for success), jqXHR.fail() (for error), and jqXHR.always() (for completion, whether success or error) methods take a function argument that is called when the request terminates. For information about the arguments this function receives, see the jqXHR Object section of the $.ajax() documentation.

The Promise interface also allows jQuery's Ajax methods, including $.get(), to chain multiple .done(), .fail(), and .always() callbacks on a single request, and even to assign these callbacks after the request may have completed. If the request is already complete, the callback is fired immediately.

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.get("example.php", function() {
  alert("success");
})
.done(function() { alert("second success"); })
.fail(function() { alert("error"); })
.always(function() { alert("finished"); });

// perform other work here ...

// Set another completion function for the request above
jqxhr.always(function(){ alert("second finished"); });

Deprecation Notice

The jqXHR.success(), jqXHR.error(), and jqXHR.complete() callback methods introduced in jQuery 1.5 are deprecated as of jQuery 1.8. To prepare your code for their eventual removal, use jqXHR.done(), jqXHR.fail(), and jqXHR.always() instead.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  dataType: "json",
  url: url,
  data: data,
  success: success
});

Data that is sent to the server is appended to the URL as a query string. If the value of the data parameter is a plain object, it is converted to a string and url-encoded before it is appended to the URL.

Most implementations will specify a success handler:

$.getJSON('ajax/test.json', function(data) {
  var items = [];

  $.each(data, function(key, val) {
    items.push('<li id="' + key + '">' + val + '</li>');
  });

  $('<ul/>', {
    'class': 'my-new-list',
    html: items.join('')
  }).appendTo('body');
});

This example, of course, relies on the structure of the JSON file:

{
  "one": "Singular sensation",
  "two": "Beady little eyes",
  "three": "Little birds pitch by my doorstep"
}

Using this structure, the example loops through the requested data, builds an unordered list, and appends it to the body.

The success callback is passed the returned data, which is typically a JavaScript object or array as defined by the JSON structure and parsed using the $.parseJSON() method. It is also passed the text status of the response.

As of jQuery 1.5, the success callback function receives a "jqXHR" object (in jQuery 1.4, it received the XMLHttpRequest object). However, since JSONP and cross-domain GET requests do not use XHR, in those cases the jqXHR and textStatus parameters passed to the success callback are undefined.

JSONP

If the URL includes the string "callback=?" (or similar, as defined by the server-side API), the request is treated as JSONP instead. See the discussion of the jsonp data type in $.ajax() for more details.

The jqXHR Object

As of jQuery 1.5, all of jQuery's Ajax methods return a superset of the XMLHTTPRequest object. This jQuery XHR object, or "jqXHR," returned by $.getJSON() implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see Deferred object for more information). The jqXHR.done() (for success), jqXHR.fail() (for error), and jqXHR.always() (for completion, whether success or error) methods take a function argument that is called when the request terminates. For information about the arguments this function receives, see the jqXHR Object section of the $.ajax() documentation.

The Promise interface in jQuery 1.5 also allows jQuery's Ajax methods, including $.getJSON(), to chain multiple .done(), .always(), and .fail() callbacks on a single request, and even to assign these callbacks after the request may have completed. If the request is already complete, the callback is fired immediately.

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.getJSON( "example.json", function() {
  console.log( "success" );
})
.done(function() { console.log( "second success" ); })
.fail(function() { console.log( "error" ); })
.always(function() { console.log( "complete" ); });

// perform other work here ...

// Set another completion function for the request above
jqxhr.complete(function() { console.log( "second complete" ); });

Deprecation Notice

The jqXHR.success(), jqXHR.error(), and jqXHR.complete() callback methods introduced in jQuery 1.5 are deprecated as of jQuery 1.8. To prepare your code for their eventual removal, use jqXHR.done(), jqXHR.fail(), and jqXHR.always() instead.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  url: url,
  dataType: "script",
  success: success
});

The script is executed in the global context, so it can refer to other variables and use jQuery functions. Included scripts can have some impact on the current page.

Success Callback

The callback is fired once the script has been loaded but not necessarily executed.

$(".result").html("<p>Lorem ipsum dolor sit amet.</p>");

Scripts are included and run by referencing the file name:

$.getScript("ajax/test.js", function(data, textStatus, jqxhr) {
   console.log(data); //data returned
   console.log(textStatus); //success
   console.log(jqxhr.status); //200
   console.log('Load was performed.');
});

Handling Errors

As of jQuery 1.5, you may use .fail() to account for errors:

$.getScript("ajax/test.js")
.done(function(script, textStatus) {
  console.log( textStatus );
})
.fail(function(jqxhr, settings, exception) {
  $( "div.log" ).text( "Triggered ajaxError handler." );
});

Prior to jQuery 1.5, the global .ajaxError() callback event had to be used in order to handle $.getScript() errors:

$( "div.log" ).ajaxError(function(e, jqxhr, settings, exception) {
  if (settings.dataType=='script') {
    $(this).text( "Triggered ajaxError handler." );
  }
});

Caching Responses

By default, $.getScript() sets the cache setting to false. This appends a timestamped query parameter to the request URL to ensure that the browser downloads the script each time it is requested. You can override this feature by setting the cache property globally using $.ajaxSetup():

$.ajaxSetup({
  cache: true
});

Alternatively, you could define a new method that uses the more flexible $.ajax() method.

This method behaves differently from using a normal JavaScript eval() in that it's executed within the global context (which is important for loading external scripts dynamically).

The $.grep() method removes items from an array as necessary so that all remaining items pass a provided test. The test is a function that is passed an array item and the index of the item within the array. Only if the test returns true will the item be in the result array.

The filter function will be passed two arguments: the current array item and its index. The filter function must return 'true' to include the item in the result array.

The jQuery.hasData() method provides a way to determine if an element currently has any values that were set using jQuery.data(). If no data is associated with an element (there is no data object at all or the data object is empty), the method returns false; otherwise it returns true.

The primary advantage of jQuery.hasData(element) is that it does not create and associate a data object with the element if none currently exists. In contrast, jQuery.data(element) always returns a data object to the caller, creating one if no data object previously existed.

Note that jQuery's event system uses the jQuery data API to store event handlers. Therefore, binding an event to an element using .on(), .bind(), .live(), .delegate(), or one of the shorthand event methods also associates a data object with that element.

The $.holdReady() method allows the caller to delay jQuery's ready event. This advanced feature would typically be used by dynamic script loaders that want to load additional JavaScript such as jQuery plugins before allowing the ready event to occur, even though the DOM may be ready. This method must be called early in the document, such as in the <head> immediately after the jQuery script tag. Calling this method after the ready event has already fired will have no effect.

To delay the ready event, first call $.holdReady(true). When the ready event should be released to execute, call $.holdReady(false). Note that multiple holds can be put on the ready event, one for each $.holdReady(true) call. The ready event will not actually fire until all holds have been released with a corresponding number of $.holdReady(false) calls and the normal document ready conditions are met. (See ready for more information.)

The $.inArray() method is similar to JavaScript's native .indexOf() method in that it returns -1 when it doesn't find a match. If the first element within the array matches value, $.inArray() returns 0.

Because JavaScript treats 0 as loosely equal to false (i.e. 0 == false, but 0 !== false), if we're checking for the presence of value within array, we need to check if it's not equal to (or greater than) -1.

$.isArray() returns a Boolean indicating whether the object is a JavaScript array (not an array-like object, such as a jQuery object).

As of jQuery 1.4 this method checks both properties on the object itself and properties inherited from prototypes (in that it doesn't use hasOwnProperty). The argument should always be a plain JavaScript Object as other types of object (DOM elements, primitive strings/numbers, host objects) may not give consistent results across browsers. To determine if an object is a plain JavaScript object, use $.isPlainObject()

Note: As of jQuery 1.3, functions provided by the browser like alert() and DOM element methods like getAttribute() are not guaranteed to be detected as functions in browsers such as Internet Explorer.

The $.isNumeric() method checks whether its argument represents a numeric value. If so, it returns true. Otherwise it returns false. The argument can be of any type.

Note: Host objects (or objects used by browser host environments to complete the execution environment of ECMAScript) have a number of inconsistencies which are difficult to robustly feature detect cross-platform. As a result of this, $.isPlainObject() may evaluate inconsistently across browsers in certain instances.

An example of this is a test against document.location using $.isPlainObject() as follows:

  console.log($.isPlainObject(document.location));

which throws an invalid pointer exception in IE8. With this in mind, it's important to be aware of any of the gotchas involved in using $.isPlainObject() against older browsers. A couple basic examples that do function correctly cross-browser can be found below.

This is used in a number of places in jQuery to determine if we're operating against a browser window (such as the current window or an iframe).

Many methods, both in jQuery and in JavaScript in general, return objects that are array-like. For example, the jQuery factory function $() returns a jQuery object that has many of the properties of an array (a length, the [] array access operator, etc.), but is not exactly the same as an array and lacks some of an array's built-in methods (such as .pop() and .reverse()).

Note that after the conversion, any special features the object had (such as the jQuery methods in our example) will no longer be present. The object is now a plain array.

If you wish to process a jQuery object — for example, $('div').map( callback ); — use .map() instead.

The $.map() method applies a function to each item in an array or object and maps the results into a new array. Prior to jQuery 1.6, $.map() supports traversing arrays only. As of jQuery 1.6 it also traverses objects.

Array-like objects — those with a .length property and a value on the .length - 1 index — must be converted to actual arrays before being passed to $.map(). The jQuery library provides $.makeArray() for such conversions.

      
// The following object masquerades as an array.
var fakeArray = {"length": 1, 0: "Addy", 1: "Subtracty"};

// Therefore, convert it to a real array
var realArray = $.makeArray( fakeArray )

// Now it can be used reliably with $.map()
$.map( realArray, function(val, i) {
  // do something
});

    

The translation function that is provided to this method is called for each top-level element in the array or object and is passed two arguments: The element's value and its index or key within the array or object.

The function can return:

• the translated value, which will be mapped to the resulting array
• null or undefined, to remove the item
• an array of values, which will be flattened into the full array

The $.merge() operation forms an array that contains all elements from the two arrays. The orders of items in the arrays are preserved, with items from the second array appended. The $.merge() function is destructive. It alters the first parameter to add the items from the second.

If you need the original first array, make a copy of it before calling $.merge(). Fortunately, $.merge() itself can be used for this duplication:

var newArray = $.merge([], oldArray);

This shortcut creates a new, empty array and merges the contents of oldArray into it, effectively cloning the array.

Prior to jQuery 1.4, the arguments should be true Javascript Array objects; use $.makeArray if they are not.

Many JavaScript libraries use $ as a function or variable name, just as jQuery does. In jQuery's case, $ is just an alias for jQuery, so all functionality is available without using $. If you need to use another JavaScript library alongside jQuery, return control of $ back to the other library with a call to $.noConflict(). Old references of $ are saved during jQuery initialization; noConflict() simply restores them.

If for some reason two versions of jQuery are loaded (which is not recommended), calling $.noConflict(true) from the second version will return the globally scoped jQuery variables to those of the first version.

<script type="text/javascript" src="other_lib.js"></script>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript">
  $.noConflict();
  // Code that uses other library's $ can follow here.
</script>

This technique is especially effective in conjunction with the .ready() method's ability to alias the jQuery object, as within callback passed to .ready() you can use $ if you wish without fear of conflicts later:

<script type="text/javascript" src="other_lib.js"></script>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript">
  $.noConflict();
  jQuery(document).ready(function($) {
    // Code that uses jQuery's $ can follow here.
  });
  // Code that uses other library's $ can follow here.
</script>

If necessary, you can free up the jQuery name as well by passing true as an argument to the method. This is rarely necessary, and if you must do this (for example, if you need to use multiple versions of the jQuery library on the same page), you need to consider that most plug-ins rely on the presence of the jQuery variable and may not operate correctly in this situation.

You can use this empty function when you wish to pass around a function that will do nothing.

This is useful for plugin authors who offer optional callbacks; in the case that no callback is given, something like jQuery.noop could execute.

The $.now() method is a shorthand for the number returned by the expression (new Date).getTime().