Undelegate is a way of removing event handlers that have been bound using .delegate(). It works virtually identically to .die() with the addition of a selector filter argument (which is required for delegation to work).

Delegate is an alternative to using the .live() method, allowing for each binding of event delegation to specific DOM elements. For example the following delegate code:

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

Is equivalent to the following code written using .live():

$("table").each(function(){
	$("td", this).live("hover", function(){
		$(this).toggleClass("hover");
	});
});

See also the .undelegate() method for a way of removing event handlers added in .delegate().

This method exists primarily for plugin developers who wish to override it and provide a better display (or more information) for the error messages.

Passing in a malformed JSON string will result in an exception being thrown. For example, the following are all malformed JSON strings:

• {test: 1} (test does not have double quotes around it).
• {'test': 1} ('test' is using single quotes instead of double quotes).

Additionally if you pass in nothing, an empty string, null, or undefined, 'null' will be returned from parseJSON. Where the browser provides a native implementation of JSON.parse, jQuery uses it to parse the string. For details on the JSON format, see http://json.org/.

This method is most useful for attaching event handlers to an element where the context is pointing back to a different object. Additionally, jQuery makes sure that even if you bind the function returned from jQuery.proxy() it will still unbind the correct function, if passed the original.

This method is a shortcut for .bind('focusout', handler).

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 from parent elements (in other words, it supports event bubbling).

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

This method is a shortcut for .bind('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.

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

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.

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.

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.

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.

jQuery.delay() is best for delaying between queued jQuery effects and such, and is not a replacement for JavaScript's native setTimeout function, which may be more appropriate for certain use cases.

Given a jQuery object that represents a set of DOM elements, the .parentsUntil() method traverses through the ancestors of these elements until it reaches an element matched by the selector passed in the method's argument. The resulting jQuery object contains all of the ancestors up to but not including the one matched by the .parentsUntil() selector. Consider a page with a basic nested list as follows:

<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 A, we can find its ancestors up to but not including <ul class="level-1"> as follows:

$('li.item-a').parentsUntil('.level-1')
    .css('background-color', 'red');

The result of this call is a red background for the level-2 list and the item II.

If the .parentsUntil() selector is not matched, or if no selector is supplied, the returned jQuery object contains all of the previous jQuery object's ancestors. For example, let's say we begin at item A again, but this time we use a selector that is not matched by any of its ancestors:

$('li.item-a').parentsUntil('.not-here')
    .css('background-color', 'red');

The result of this call is a red background-color style applied to the level-2 list, the item II, the level-1 list, the <body> element, and the <html> element.

Given a jQuery object that represents a set of DOM elements, the .prevUntil() method allows us to search through the predecessors of these elements in the DOM tree, stopping when it reaches an element matched by the method's argument. The new jQuery object that is returned contains all previous siblings up to but not including the one matched by the .prevUntil() selector.

If the selector is not matched or is not supplied, all previous siblings will be selected; in these cases it selects the same elements as the .prevAll() method does when no filter selector is provided.

Consider a page with a simple definition list as follows:

<dl>
  <dt>term 1</dt>
  <dd>definition 1-a</dd>
  <dd>definition 1-b</dd>
  <dd>definition 1-c</dd>
  <dd>definition 1-d</dd>

  <dt id="term-2">term 2</dt>
  <dd>definition 2-a</dd>
  <dd>definition 2-b</dd>
  <dd>definition 2-c</dd>

  <dt>term 3</dt>
  <dd>definition 3-a</dd>
  <dd>definition 3-b</dd>
</dl>

If we begin at the second term, we can find the elements which come after it until a preceding <dt>.

$('#term-2').prevUntil('dt').css('background-color', 'red');

The result of this call is a red background behind definitions 1-a, 1-b, 1-c, and 1-d.

Given a jQuery object that represents a set of DOM elements, the .nextUntil() method allows us to search through the successors of these elements in the DOM tree, stopping when it reaches an element matched by the method's argument. The new jQuery object that is returned contains all following siblings up to but not including the one matched by the .nextUntil() selector.

If the selector is not matched or is not supplied, all following siblings will be selected; in these cases it selects the same elements as the .nextAll() method does when no filter selector is provided.

Consider a page with a simple definition list as follows:

<dl>
  <dt>term 1</dt>
  <dd>definition 1-a</dd>
  <dd>definition 1-b</dd>
  <dd>definition 1-c</dd>
  <dd>definition 1-d</dd>

  <dt id="term-2">term 2</dt>
  <dd>definition 2-a</dd>
  <dd>definition 2-b</dd>
  <dd>definition 2-c</dd>

  <dt>term 3</dt>
  <dd>definition 3-a</dd>
  <dd>definition 3-b</dd>
</dl>

If we begin at the second term, we can find the elements which come after it until a following <dt>.

$('#term-2').nextUntil('dt').css('background-color', 'red');

The result of this call is a red background behind definitions 2-a, 2-b, and 2-c.

This property was introduced in DOM level 3.

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).

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

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.

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.

event.which 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.

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

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

This can be the element that registered for the event or a child 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.

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.

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 we had a simple unordered list on the page:

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

We can select the list items and iterate across them:

$('li').each(function(index) {
    alert(index + ': ' + $(this).text());
  });
  

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

0: foo
1: bar

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

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).

Note: This is a low-level method, you should probably use .removeData() instead.

The jQuery.removeData() method allows us to remove values that were previously set using jQuery.data(). When called with the name of a key, jQuery.removeData() deletes that particular value; when called with no arguments, all values are removed.

Note: This is a low-level method; you should probably use .data() instead.

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 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 is a low-level method; you should probably use .data() instead.

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 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.

Note: This is a low-level method, you should probably use .queue() instead.

Note: This is a low-level method, you should probably use .queue() instead.

Every element can have one or more queues of functions attached to it by jQuery. In most applications, only one queue (called fx) is used. Queues allow a sequence of actions to be called on an element asynchronously, without halting program execution.

The jQuery.queue() method allows us to directly manipulate this queue of functions. Calling jQuery.queue() with a callback is particularly useful; it allows us to place a new function at the end of the queue.

Note that when adding a function with jQuery.queue(), we should ensure that jQuery.dequeue() is eventually called so that the next function in line executes.

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.

.toArray() returns all of the elements in the jQuery set:

alert($('li').toArray());

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

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

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).

This method is a shortcut for .bind('keydown', handler) in the first variation, and .trigger('keydown') in the second.

The keydown event is sent to an element when the user first presses a key on the keyboard. It can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Hello there" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the input field:

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

Now when the insertion point is inside the field and a key is pressed, the alert is displayed:

Handler for .keydown() called.

We can trigger the event manually when another element is clicked:

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

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

If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the document object. Because of event bubbling, all key presses will make their way up the DOM to the document object unless explicitly stopped.

To determine which key was pressed, we can examine the event object that is passed to the handler function. While browsers use differing properties to store this information, jQuery normalizes the .which property so we can reliably use it to retrieve the key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, .keypress() may be a better choice.

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 original element 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

The .removeData() method allows us to remove values that were previously set using .data(). When called with the name of a key, .removeData() deletes that particular value; when called with no arguments, all values are removed.

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('foo'); // 52
$('body').data(); // {foo: 52, bar: { myType: 'test', count: 40 }}

Setting an element's data object with .data(obj) replaces all data previously stored with that element. 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. Until jQuery 1.4.2, jQuery itself used the .data() method to save information about events that have been bound to the element, using a data item named 'events'.

$('body').data('foo', 52);
$('body').data({one: 1, two: 2});

$('body').data('foo'); // undefined
$('body').data(); // {one: 1, two: 2}

Due to the way browsers interact with plugins and external code, the .data() method cannot be used on <object>, <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 nothing was set on that element, an empty string is returned:

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).

The .get() method grants us access to the DOM nodes underlying each jQuery object. Suppose we had a simple unordered list on the page:

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

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

alert($('li').get());

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

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

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

($('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:

alert($('li')[0]);

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

alert($('li').get(-1));

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

<li id="bar">

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

We can determine the number of list items by calling .size():

alert('Size: ' + $('li').size());

This will alert the count of items:

Size: 2

You should use the .length property instead, which is slightly faster.

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 we need to use another JavaScript library alongside jQuery, we can return control of $ back to the other library with a call to $.noConflict():

<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() we can use $ if we 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, we can free up the jQuery name as well by passing true as an argument to the method. This is rarely necessary, and if we must do this (for example, if we need to use multiple versions of the jQuery library on the same page), we need to consider that most plug-ins rely on the presence of the jQuery variable and may not operate correctly in this situation.

The :selected selector works for <option> elements. It does not work for checkboxes or radio inputs; use :checked for them.

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

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') should be used 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') should be used 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 $(':file') is equivalent to $('*:file'), so $('input:file') should be used instead.

The :submit selector typically applies to button or input elements. Note that some browsers treat <button> element as type="default" implicitly while others (such as Internet Explorer) do not.

$(':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.

$(':radio') is equivalent to $('[type=radio]'). 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 $(':radio') is equivalent to $('*:radio'), so $('input:radio') should be used instead.

To select a set of associated radio buttons, you might use: $('input[name=gender]:radio')

$(':password') is equivalent to $('[type=password]'). 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 $(':password') is equivalent to $('*:password'), so $('input:password') should be used instead.

$(':text') is equivalent to $('[type=text]') and thus selects all <input type="text"> elements. 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 $(':text') is equivalent to $('*:text'), so $('input:text') should be used instead.

The :input selector basically selects all form controls.

If the parent has other child elements, nothing is matched.

While :last matches only a single element, :last-child can match more than one: one for each parent.

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).

Because jQuery's implementation of :nth-child(n) is strictly derived from the CSS specification, the value of n is "1-indexed", meaning that the counting starts at 1. For all other selector expressions, however, jQuery follows JavaScript's "0-indexed" counting. Therefore, given a single <ul> containing two <li>s, $('li:nth-child(1)') selects the first <li> while $('li:eq(1)') selects the second.

The :nth-child(n) pseudo-class is easily confused with :eq(n), even though the two can result in dramatically different matched elements. With :nth-child(n), all children are counted, regardless of what they are, and the specified element is selected only if it matches the selector attached to the pseudo-class. With :eq(n) only the selector attached to the pseudo-class is counted, not limited to children of any other element, and the (n+1)th one (n is 0-based) is selected.

Further discussion of this unusual usage can be found in the W3C CSS specification.

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

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 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 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.

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

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. During animations to show an element, the element is considered to be visible at the start at the animation.

How :visible is calculated was changed in jQuery 1.3.2. The release notes outline the changes in more detail.

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. During animations to show an element, the element is considered to be visible at the start at 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.

This is the inverse of :empty.

One important thing to note regarding the use of :parent (and :empty) 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.

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

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.

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 bare words or surrounded by quotation marks. The text must have matching case to be selected.

index-related selectors

The index-related selectors (including this "less 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:lt(1)') selects the first element in the document with the class myclass, rather than selecting no elements. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

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.

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.

In particular, note that the 0-based indexing means that, counter-intuitively, :odd selects the second element, fourth element, and so on within the matched set.

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.

All selectors are accepted inside :not(), for example: :not(div a) and :not(div,a).

Note that :last selects a single element by filtering the current jQuery collection and matching the last element within it.

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.

The notable difference between (prev + next) and (prev ~ siblings) is their respective reach. While the former reaches only to the immediately following sibling element, the latter extends that reach to all following sibling elements.

One important point to consider with both the next adjacent sibling selector (prev + next) and the general sibling selector (prev ~ siblings) is that the elements on either side of the combinator must share the same parent.

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.

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

You can specify any number of selectors to combine into a single result. This multiple expression combinator is an efficient way to select disparate elements. The order of the DOM elements in the returned jQuery object may not be identical, as they will be in document order. An alternative to this combinator is the .add() method.

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

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

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

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.

As always, remember that as a developer, your time is typically the most valuable resource. Do not focus on optimization of selector speed unless it is clear that performance needs to be improved.

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.

This method is a shortcut for .bind('scroll', handler) in the first variation, and .trigger('scroll') in the second.

The scroll event is sent to an element when the user scrolls to a different place in the element. It applies to window objects, but also to scrollable frames and elements with the overflow CSS property set to scroll (or auto when the element's explicit height is less than the height of its contents).

For example, consider the HTML:

<div id="target" style="overflow: scroll; width: 200px; height: 100px;">
  Lorem ipsum dolor sit amet, consectetur adipisicing elit,
  sed do eiusmod tempor incididunt ut labore et dolore magna
  aliqua. Ut enim ad minim veniam, quis nostrud exercitation
  ullamco laboris nisi ut aliquip ex ea commodo consequat.
  Duis aute irure dolor in reprehenderit in voluptate velit
  esse cillum dolore eu fugiat nulla pariatur. Excepteur
  sint occaecat cupidatat non proident, sunt in culpa qui
  officia deserunt mollit anim id est laborum.
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The style definition is present to make the target element small enough to be scrollable:

The scroll event handler can be bound to this element:

$('#target').scroll(function() {
  $('#log').append('<div>Handler for .scroll() called.</div>');
});

Now when the user scrolls the text up or down, one or more messages are appended to <div id="log"></div>:

Handler for .scroll() called.

We can trigger the event manually when another element is clicked:

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

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

A scroll event is sent whenever the element's scroll position changes, regardless of the cause. A mouse click or drag on the scroll bar, dragging inside the element, pressing the arrow keys, or using the mouse's scroll wheel could cause this event.

This method is a shortcut for .bind('resize', handler) in the first variation, and .trigger('resize') in the second.

The resize event is sent to the window element when the size of the browser window changes:

$(window).resize(function() {
  $('#log').append('<div>Handler for .resize() called.</div>');
});

Now whenever the browser window's size is changed, the message is appended to <div id="log"> one or more times, depending on the browser.

Code in a resize handler should never rely on the number of times the handler is called. Depending on implementation, resize events can be sent continuously as the resizing is in progress (the typical behavior in Internet Explorer and WebKit-based browsers such as Safari and Chrome), or only once at the end of the resize operation (the typical behavior in Firefox).

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.

Every element can have one to many queues of functions attached to it by jQuery. In most applications, only one queue (called fx) is used. Queues allow a sequence of actions to be called on an element asynchronously, without halting program execution. The typical example of this is calling multiple animation methods on an element. For example:

$('#foo').slideUp().fadeIn();

When this statement is executed, the element begins its sliding animation immediately, but the fading transition is placed on the fx queue to be called only once the sliding transition is complete.

The .queue() method allows us to directly manipulate this queue of functions. Calling .queue() with a callback is particularly useful; it allows us to place a new function at the end of the queue.

This feature is similar to providing a callback function with an animation method, but does not require the callback to be given at the time the animation is performed.

$('#foo').slideUp();
$('#foo').queue(function() {
  alert('Animation complete.');
  $(this).dequeue();
});

This is equivalent to:

$('#foo').slideUp(function() {
  alert('Animation complete.');
});

Note that when adding a function with .queue(), we should ensure that .dequeue() is eventually called so that the next function in line executes.

In jQuery 1.4 the function that's called is passed in another function, as the first argument, that when called automatically dequeues the next item and keeps the queue moving. You would use it like so:

$("#test").queue(function(next) {
    // Do some stuff...
    next();
});

This method is a shortcut for .bind('keyup', handler) in the first variation, and .trigger('keyup') in the second.

The keyup event is sent to an element when the user releases a key on the keyboard. It can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Hello there" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the input field:

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

Now when the insertion point is inside the field and a key is pressed and released, the alert is displayed:

Handler for .keyup() called.

We can trigger the event manually when another element is clicked:

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

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

If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the document object. Because of event bubbling, all key presses will make their way up the DOM to the document object unless explicitly stopped.

To determine which key was pressed, we can examine the event object that is passed to the handler function. While browsers use differing attributes to store this information, jQuery normalizes the .which attribute so we can reliably use it to retrieve the key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, .keypress() may be a better choice.

This method is a shortcut for .bind('keypress', handler) in the first variation, and .trigger('keypress') in the second.

The keypress event is sent to an element when the browser registers keyboard input. This is similar to the keydown event, except in the case of key repeats. If the user presses and holds a key, a keydown event is triggered once, but separate keypress events are triggered for each inserted character. In addition, modifier keys (such as Shift) cause keydown events but not keypress events.

A keypress event handler can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.

For example, consider the HTML:

<form>
	<fieldset>
  	<input id="target" type="text" value="Hello there" />
	</fieldset>
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the input field:

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

Now when the insertion point is inside the field and a key is pressed, the alert is displayed:

Handler for .keypress() called.

The message repeats if the key is held down. We can trigger the event manually when another element is clicked:

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

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

If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the document object. Because of event bubbling, all key presses will make their way up the DOM to the document object unless explicitly stopped.

To determine which character was entered, we can examine the event object that is passed to the handler function. While browsers use differing attributes to store this information, jQuery normalizes the .which attribute so we can reliably use it to retrieve the character code.

Note that keydown and keyup provide a code indicating which key is pressed, while keypress indicates which character was entered. For example, a lowercase "a" will be reported as 65 by keydown and keyup, but as 97 by keypress. An uppercase "A" is reported as 65 by all events. Because of this distinction, when catching special keystrokes such as arrow keys, .keydown() or .keyup() is a better choice.

This method is a shortcut for .bind('submit', handler) in the first variation, and .trigger('submit') in the second.

The submit event is sent to an element when the user is attempting to submit a form. It can only be attached to <form> elements. Forms can be submitted either by clicking an explicit <input type="submit">, <input type="image">, or <button type="submit">, or by pressing Enter when certain form element has focus.

Depending on the browser, the Enter key may only cause a form submission if the form has exactly one text field, or only when there is a submit button present. The interface should not rely on a particular behavior for this key unless the issue is forced by observing the keypress event for presses of the Enter key.

For example, consider the HTML:

<form id="target" action="destination.html">
  <input type="text" value="Hello there" />
  <input type="submit" value="Go" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the form:

$('#target').submit(function() {
  alert('Handler for .submit() called.');
  return false;
});

Now when the form is submitted, the message is alerted. This happens prior to the actual submission, so we can cancel the submit action by calling .preventDefault() on the event object or by returning false from our handler. We can trigger the event manually when another element is clicked:

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

After this code executes, clicks on Trigger the handler will also display the message. In addition, the default submit action on the form will be fired, so the form will be submitted.

The JavaScript submit event does not bubble in Internet Explorer. However, scripts that rely on event delegation with the submit event will work consistently across browsers as of jQuery 1.4, which has normalized the event's behavior.

This method is a shortcut for .bind('select', handler) in the first variation, and .trigger('select') in the second.

The select event is sent to an element when the user makes a text selection inside it. This event is limited to <input type="text"> fields and <textarea> boxes.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Hello there" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the text input:

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

Now when any portion of the text is selected, the alert is displayed. Merely setting the location of the insertion point will not trigger the event. We can trigger the event manually when another element is clicked:

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

After this code executes, clicks on the Trigger button will also alert the message:

Handler for .select() called.

In addition, the default select action on the field will be fired, so the entire text field will be selected.

The method for retrieving the current selected text differs from one browser to another. A number of jQuery plug-ins offer cross-platform solutions.

This method is a shortcut for .bind('change', handler) in the first variation, and .trigger('change') in the second.

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 we 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. We can trigger the event manually when another element is clicked:

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

After this code executes, clicks on Trigger the handler will also alert the message. The message will be displayed 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 now bubbles, and works identically to all other browsers, in Internet Explorer.

This method is a shortcut for .bind('blur', handler) in the first variation, and .trigger('blur') in the second.

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 and we click elsewhere, or tab away from it, the alert is displayed:

Handler for .blur() called.

We can trigger the event when another element is clicked:

$('#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.

• This method is a shortcut for .bind('focus', handler) in the first variation, and .trigger('focus') in the second.
• 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 if we click on the first field, or tab to it from another field, the alert is displayed:

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.

Triggering the focus on hidden elements causes an error in Internet Explorer. Take care to only call .focus() without parameters on elements that are visible.

This method is a shortcut for .bind('mousemove', handler) in the first variation, and .trigger('mousemove') in the second.

The mousemove event is sent to an element when the mouse pointer moves inside the element. Any HTML element can receive this event.

For example, consider the HTML:

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

The event handler can be bound to the target:

$('#target').mousemove(function(event) {
  var msg = 'Handler for .mousemove() called at ' + event.pageX + ', ' + event.pageY;
  $('#log').append('<div> + msg + '</div>');
});

Now when the mouse pointer moves within the target button, the messages are appended to <div id="log">:

Handler for .mousemove() called at (399, 48)
Handler for .mousemove() called at (398, 46)
Handler for .mousemove() called at (397, 44)
Handler for .mousemove() called at (396, 42)

We can also trigger the event when the second button is clicked:

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

After this code executes, clicks on the Trigger button will also append the message:

Handler for .mousemove() called at (undefined, undefined)

When tracking mouse movement, we usually need to know the actual position of the mouse pointer. The event object that is passed to the handler contains some information about the mouse coordinates. Properties such as .clientX, .offsetX, and .pageX are available, but support for them differs between browsers. Fortunately, jQuery normalizes the .pageX and .pageY attributes so that they can be used in all browsers. These attributes provide the X and Y coordinates of the mouse pointer relative to the top-left corner of the page, as illustrated in the example output above.

We need to remember that the mousemove event is triggered whenever the mouse pointer moves, even for a pixel. This means that hundreds of events can be generated over a very small amount of time. If the handler has to do any significant processing, or if multiple handlers for the event exist, this can be a serious performance drain on the browser. It is important, therefore, to optimize mousemove handlers as much as possible, and to unbind them as soon as they are no longer needed.

A common pattern is to bind the mousemove handler from within a mousedown hander, and to unbind it from a corresponding mouseup handler. If implementing this sequence of events, remember that the mouseup event might be sent to a different HTML element than the mousemove event was. To account for this, the mouseup handler should typically be bound to an element high up in the DOM tree, such as <body>.

The .hover() method binds handlers for both mouseenter and mouseleave events. We 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.

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

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

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

This method is a shortcut for .bind('mouseleave', handler) in the first variation, and .trigger('mouseleave') in the second.

The mouseleave JavaScript event is proprietary to Internet Explorer. Because of the event's general utility, jQuery simulates this event so that it can be used regardless of browser. This event is sent to an element when the mouse pointer leaves the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseleave(function() {
  $('#log').append('<div>Handler for .mouseleave() called.</div>');
});

Now when the mouse pointer moves out of the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseleave();
});

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

The mouseleave event differs from mouseout in the way it handles event bubbling. If mouseout were used in this example, then when the mouse pointer moved out of the Inner element, the handler would be triggered. This is usually undesirable behavior. The mouseleave event, on the other hand, only triggers its handler when the mouse leaves the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse leaves the Outer element, but not the Inner element.

This method is a shortcut for .bind('mouseenter', handler) in the first variation, and .trigger('mouseenter') in the second.

The mouseenter JavaScript event is proprietary to Internet Explorer. Because of the event's general utility, jQuery simulates this event so that it can be used regardless of browser. This event sent to an element when the mouse pointer enters the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseenter(function() {
  $('#log').append('<div>Handler for .mouseenter() called.</div>');
});

Now when the mouse pointer moves over the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseenter();
});

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

The mouseenter event differs from mouseover in the way it handles event bubbling. If mouseover were used in this example, then when the mouse pointer moved over the Inner element, the handler would be triggered. This is usually undesirable behavior. The mouseenter event, on the other hand, only triggers its handler when the mouse enters the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse enters the Outer element, but not the Inner element.

This method is a shortcut for .bind('mouseout', handler) in the first variation, and .trigger('mouseout') in the second.

The mouseout event is sent to an element when the mouse pointer leaves the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseout(function() {
  $('#log').append('Handler for .mouseout() called.');
});

Now when the mouse pointer moves out of the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseout();
});

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

This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves out of the Inner element in this example, a mouseout event will be sent to that, then trickle up to Outer. This can trigger the bound mouseout handler at inopportune times. See the discussion for .mouseleave() for a useful alternative.

This method is a shortcut for .bind('mouseover', handler) in the first variation, and .trigger('mouseover') in the second.

The mouseover event is sent to an element when the mouse pointer enters the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseover(function() {
  $('#log').append('<div>Handler for .mouseover() called.</div>');
});

Now when the mouse pointer moves over the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseover();
});

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

This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves over the Inner element in this example, a mouseover event will be sent to that, then trickle up to Outer. This can trigger our bound mouseover handler at inopportune times. See the discussion for .mouseenter() for a useful alternative.

This method is a shortcut for .bind('dblclick', handler) in the first variation, and .trigger('dblclick') in the second. 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 if we double-click on this element, the alert is displayed:

Handler for .dblclick() called.

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

$('#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 and others only one. If an interface that reacts differently to single- and double-clicks cannot be avoided, then the dblclick event should be simulated within the click handler. We can achieve this by saving a timestamp in the handler, and then comparing the current time to the saved timestamp on subsequent clicks. If the difference is small enough, we can treat the click as a double-click.

This method is a shortcut for .bind('click', handler) in the first variation, and .trigger('click') in the second.

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.

This method is a shortcut for .bind('mouseup', handler) in the first variation, and .trigger('mouseup') in the second.

The mouseup event is sent to an element when the mouse pointer is over the element, and the mouse button is 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').mouseup(function() {
  alert('Handler for .mouseup() called.');
});

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

Handler for .mouseup() called.

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

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

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

If the user clicks outside an element, drags onto it, and releases the button, this is still counted as a mouseup event. This sequence of actions is not treated as a button press in most user interfaces, so it is usually better to use the click event unless we know that the mouseup event is preferable for a particular situation.

This method is a shortcut for .bind('mousedown', handler) in the first variation, and .trigger('mousedown') in the second.

The mousedown event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed. 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').mousedown(function() {
  alert('Handler for .mousedown() called.');
});

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

Handler for .mousedown() called.

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

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

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

The mousedown event is sent when any mouse button is clicked. To act only on specific buttons, we can use the event object's which property. Not all browsers support this property (Internet Explorer uses button instead), but jQuery normalizes the property so that it is safe to use in any browser. The value of which will be 1 for the left button, 2 for the middle button, or 3 for the right button.

This event is primarily useful for ensuring that the primary button was used to begin a drag operation; if ignored, strange results can occur when the user attempts to use a context menu. While the middle and right buttons can be detected with these properties, this is not reliable. In Opera and Safari, for example, right mouse button clicks are not detectable by default.

If the user clicks on an element, drags away from it, and releases the button, this is still counted as a mousedown event. This sequence of actions is treated as a "canceling" of the button press in most user interfaces, so it is usually better to use the click event unless we know that the mousedown event is preferable for a particular situation.

This method is a shortcut for .bind('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:

<img src="missing.png" alt="Book" id="book" />

The event handler can be bound to the image:

$('#book').error(function() {
  alert('Handler for .error() called.')
});

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.

This event may not be correctly fired when the page is served locally. Since error relies on normal HTTP status codes, it will generally not be triggered if the URL uses the file: protocol.

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.

This method is a shortcut for .bind('unload', handler).

The unload event is sent to the window element when the user navigates away from the page. This could mean one of many things. The user could have clicked on a link to leave the page, or typed in a new URL in the address bar. The forward and back buttons will trigger the event. Closing the browser window will cause the event to be triggered. Even a page reload will first create an unload event.

The exact handling of the unload event has varied from version to version of browsers. For example, some versions of Firefox trigger the event when a link is followed, but not when the window is closed. In practical usage, behavior should be tested on all supported browsers, and contrasted with the proprietary beforeunload event.

Any unload event handler should be bound to the window object:

$(window).unload(function() {
  alert('Handler for .unload() called.');
});

After this code executes, the alert will be displayed whenever the browser leaves the current page. It is not possible to cancel the unload event with .preventDefault(). This event is available so that scripts can perform cleanup when the user leaves the page.

This method is a shortcut for .bind('load', handler).

The load event is sent to an element when it and all sub-elements have been completely loaded. This event can be sent to any element associated with a URL: images, scripts, frames, iframes, and the window object.

It is possible that the load event will not be triggered if the image is loaded from the browser cache. To account for this possibility, we can use a special load event that fires immediately if the image is ready. event.special.load is currently available as a plugin.

For example, consider a page with a simple image:

<img src="book.png" alt="Book" id="book" />

The event handler can be bound to the image:

$('#book').load(function() {
  // Handler for .load() called.
});

As soon as the image has been loaded, the handler is called.

In general, it is not necessary to wait for all images to be fully loaded. If code can be executed earlier, it is usually best to place it in a handler sent to the .ready() method.

The Ajax module also has a method named .load(). Which one is fired depends on the set of arguments passed.

While JavaScript provides the load event for executing code when a page is rendered, this event does not get triggered until all assets such as images have been completely received. In most cases, the script can be run as soon as the DOM hierarchy has been fully constructed. The handler passed to .ready() is guaranteed to be executed after the DOM is ready, so this is usually the best place to attach all other event handlers and run other jQuery code. When using scripts that rely on the value of CSS style properties, it's important to reference external stylesheets or embed style elements before referencing the scripts.

In cases where code relies on loaded assets (for example, if the dimensions of an image are required), the code should be placed in a handler for the load event instead.

The .ready() method is generally incompatible with the <body onload=""> attribute. If load must be used, either do not use .ready() or use jQuery's .load() method to attach load event handlers to the window or to more specific items, like images.

All three of the following syntaxes are equivalent:

• $(document).ready(handler)
• $().ready(handler) (this is not recommended)
• $(handler)

There is also $(document).bind("ready", handler). This behaves similarly to the ready method but with one exception: If the ready event has already fired and you try to .bind("ready") the bound handler will not be executed.

The .ready() method can only be called on a jQuery object matching the current document, so the selector can be omitted.

The .ready() method is typically used with an anonymous function:

$(document).ready(function() {
  // Handler for .ready() called.
});

If .ready() is called after the DOM has been initialized, the new handler passed in will be executed immediately.

Aliasing the jQuery Namespace

When using another JavaScript library, we may wish to call $.noConflict() to avoid namespace difficulties. When this function is called, the $ shortcut is no longer available, forcing us to write jQuery each time we would normally write $. However, the handler passed to the .ready() method can take an argument, which is passed the global jQuery object. This means we can rename the object within the context of our .ready() handler without affecting other code:

jQuery(document).ready(function($) {
  // Code using $ as usual goes here.
});

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

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

The $.browser property allows us to detect which web browser 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, but there are no immediate plans to remove it.

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
• Mozilla/Firefox/Flock/Camino: 1.7.12, 1.8.1.3, 1.9
• Opera: 9.20
• Safari/Webkit: 312.8, 418.9

Note that IE8 claims to be 7 in Compatibility View.

This method is a variation on the basic .bind() method for attaching event handlers to elements. When .bind() is called, the elements that the jQuery object refers to get the handler attached; elements that get introduced later do not, so they would require another .bind() call. For instance, consider the HTML:

<body>
  <div class="clickme">
    Click here
  </div>
</body>

We can bind a simple click handler to this element:

$('.clickme').bind('click', function() {
  // Bound handler called.
});

When the element is clicked, the handler is called. However, suppose that after this, another element is added:

$('body').append('<div class="clickme">Another target</div>');

This new element also matches the selector .clickme, but since it was added after the call to .bind(), clicks on it will do nothing.

The .live() method provides an alternative to this behavior. If we bind a click handler to the target element using this method:

$('.clickme').live('click', function() {
  // Live handler called.
});

And then later add a new element:

$('body').append('<div class="clickme">Another target</div>');

Then clicks on the new element will also trigger the handler.

Event Delegation

The .live() method is able to affect elements that have not yet been added to the DOM through the use of event delegation: a handler bound to an ancestor element is responsible for events that are triggered on its descendants. The handler passed to .live() is never bound to an element; instead, .live() binds a special handler to the root of the DOM tree. In our example, when the new element is clicked, the following steps occur:

1. A click event is generated and passed to the <div> for handling.
2. No handler is directly bound to the <div>, so the event bubbles up the DOM tree.
3. The event bubbles up until it reaches the root of the tree, which is where .live() binds its special handlers by default.
   * As of jQuery 1.4, event bubbling can optionally stop at a DOM element "context".
4. The special click handler bound by .live() executes.
5. This handler tests the target of the event object to see whether it should continue. This test is performed by checking if $(event.target).closest('.clickme') is able to locate a matching element.
6. If a matching element is found, the original handler is called on it.

Because the test in step 5 is not performed until the event occurs, elements can be added at any time and still respond to events.

See the discussion for .bind() for more information on event binding.

Multiple Events

As of jQuery 1.4.1 .live() can accept multiple, space-separated events, similar to the functionality provided in .bind(). For example, we can "live bind" the mouseover and mouseout events at the same time like so:

$('.hoverme').live('mouseover mouseout', function(event) {
  if (event.type == 'mouseover') {
    // do something on mouseover
  } else {
    // do something on mouseout
  }
});

Event Data

As of jQuery 1.4, the optional eventData parameter allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. See the .bind() method's "Passing Event Data" discussion for more information.

Event Context

As of jQuery 1.4, live events can be bound to a DOM element "context" rather than to the default document root. To set this context, we use the jQuery() function's second argument, passing in a single DOM element (as opposed to a jQuery collection or a selector).

$('div.clickme', $('#container')[0]).live('click', function() {
  // Live handler called.
});

The live handler in this example is called only when <div class="clickme"> is a descendant of an element with an ID of "container."

Caveats

The .live() technique is useful, but due to its special approach cannot be simply substituted for .bind() in all cases. Specific differences include:

• DOM traversal methods are not fully supported for finding elements to send to .live(). Rather, the .live() method should always be called directly after a selector, as in the example above.
• To stop further handlers from executing after one bound using .live(), the handler must return false. Calling .stopPropagation() will not accomplish this.
• In jQuery 1.3.x only the following JavaScript events (in addition to custom events) could be bound with .live(): click, dblclick, keydown, keypress, keyup, mousedown, mousemove, mouseout, mouseover, and mouseup.

• As of jQuery 1.4 the .live() method supports custom events as well as all JavaScript events. As of jQuery 1.4.1 even focus and blur work with live (mapping to the more appropriate, bubbling, events focusin and focusout).
• As of jQuery 1.4.1 the hover event can be specified (mapping to "mouseenter mouseleave").

The .triggerHandler() method behaves similarly to .trigger(), with the following exceptions:

• The .triggerHandler() method does not cause the default behavior of an event to occur (such as a form submission).
• While .trigger() will operate on all elements matched by the jQuery object, .triggerHandler() only affects the first matched element.
• Events created with .triggerHandler() do not bubble up the DOM hierarchy; if they are not handled by the target element directly, they do nothing.
• Instead of returning the jQuery object (to allow chaining), .triggerHandler() returns whatever value was returned by the last handler it caused to be executed. If no handlers are triggered, it returns undefined

For more information on this method, see the discussion for .trigger().

Any event handlers attached with .bind() or one of its shortcut methods are triggered when the corresponding event occurs. They can be fired manually, however, with the .trigger() method. A call to .trigger() executes the handlers in the same order they would be if the event were triggered naturally by the user:

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

While .trigger() simulates an event activation, complete with a synthesized event object, it does not perfectly replicate a naturally-occurring event.

To trigger handlers bound via jQuery without also triggering the native event, use .triggerHandler() instead.

When we define a custom event type using the .bind() method, the second argument to .trigger() can become useful. For example, suppose we have bound a handler for the custom event to our element instead of the built-in click event as we did above:

$('#foo').bind('custom', function(event, param1, param2) {
  alert(param1 + "\n" + param2);
});
$('#foo').trigger('custom', ['Custom', 'Event']);

The event object is always passed as the first parameter to an event handler, but if additional parameters are specified during a .trigger() call as they are here, these parameters will be passed along to the handler as well.

Note the difference between the extra parameters we're passing here and the eventData parameter to the .bind() method. Both are mechanisms for passing information to an event handler, but the extraParameters argument to .trigger() allows information to be determined at the time the event is triggered, while the eventData argument to .bind() requires the information to be already computed at the time the handler is bound.

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, we can set up a basic Ajax load request:

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

We can attach our event handler to any element:

$('.log').ajaxComplete(function() {
  $(this).text('Triggered ajaxComplete handler.');
});

Now, we can make an Ajax request using any jQuery method:

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

When the user clicks the button and the Ajax request completes, the log message is displayed.

Note: Because .ajaxComplete() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

All ajaxComplete handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can 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, we can restrict our callback to only handling events dealing with a particular URL:

$('.log').ajaxComplete(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxComplete handler.');
  }
});

This method is identical to .bind(), except that the handler is unbound after its first invocation. For example:

$('#foo').one('click', function() {
  alert('This will be displayed only once.');
});

After the code is executed, a click on the element with ID foo will display the alert. Subsequent clicks will do nothing. This code is equivalent to:

$('#foo').bind('click', function(event) {
  alert('This will be displayed only once.');
  $(this).unbind(event);
});

In other words, explicitly calling .unbind() from within a regularly-bound handler has exactly the same effect.

The .serializeArray() method creates a JavaScript array of objects, ready to be encoded as a JSON string. It operates on a jQuery object representing a set of form elements. The form elements can be of several types:

<form>
  <div><input type="text" name="a" value="1" id="a" /></div>
  <div><input type="text" name="b" value="2" id="b" /></div>
  <div><input type="hidden" name="c" value="3" id="c" /></div>
  <div>
    <textarea name="d" rows="8" cols="40">4</textarea>
  </div>
  <div><select name="e">
    <option value="5" selected="selected">5</option>
    <option value="6">6</option>
    <option value="7">7</option>
  </select></div>
  <div>
    <input type="checkbox" name="f" value="8" id="f" />
  </div>
  <div>
    <input type="submit" name="g" value="Submit" id="g" />
  </div>
</form>

The .serializeArray() method uses the standard W3C rules for successful controls to determine which elements it should include; in particular the element cannot be disabled and must contain a name attribute. No submit button value is serialized since the form was not submitted using a button. Data from file select elements is not serialized.

This method can act on a jQuery object that has selected individual form elements, such as <input>, <textarea>, and <select>. However, it is typically easier to select the <form> tag itself for serialization:

$('form').submit(function() {
  alert($(this).serializeArray());
  return false;
});

This produces the following data structure:

[
  {
    name: a
    value: 1
  },
  {
    name: b
    value: 2
  },
  {
    name: c
    value: 3
  },
  {
    name: d
    value: 4
  },
  {
    name: e
    value: 5
  }
]

The .serialize() method creates a text string in standard URL-encoded notation. It operates on a jQuery object representing a set of form elements. The form elements can be of several types:

<form>
  <div><input type="text" name="a" value="1" id="a" /></div>
  <div><input type="text" name="b" value="2" id="b" /></div>
  <div><input type="hidden" name="c" value="3" id="c" /></div>
  <div>
    <textarea name="d" rows="8" cols="40">4</textarea>
  </div>
  <div><select name="e">
    <option value="5" selected="selected">5</option>
    <option value="6">6</option>
    <option value="7">7</option>
  </select></div>
  <div>
    <input type="checkbox" name="f" value="8" id="f" />
  </div>
  <div>
    <input type="submit" name="g" value="Submit" id="g" />
  </div>
</form>

The .serialize() method can act on a jQuery object that has selected individual form elements, such as <input>, <textarea>, and <select>. However, it is typically easier to select the <form> tag itself for serialization:

$('form').submit(function() {
  alert($(this).serialize());
  return false;
});

This produces a standard-looking query string:

a=1&b=2&c=3&d=4&e=5

Note: Only "successful controls" are serialized to the string. No submit button value is serialized since the form was not submitted using a button. For a form element's value to be included in the serialized string, the element must have a name attribute. Data from file select elements is not serialized.

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().

For example, we could set a default for the URL parameter before pinging the server repeatedly:

$.ajaxSetup({
  url: 'ping.php',
});

Now each time an Ajax request is made, this URL will be used automatically:

$.ajax({
  data: {'name': 'Tim'},
});

Note: Global callback functions should be set with their respective global Ajax event handler methods-.ajaxStart(), .ajaxStop(), .ajaxComplete(), .ajaxError(), .ajaxSuccess(), .ajaxSend()-rather than within the settings object for $.ajaxSetup().

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, we can set up a basic Ajax load request:

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

We can attach our event handler to any element:

$('.log').ajaxSuccess(function() {
  $(this).text('Triggered ajaxSuccess handler.');
});

Now, we can make an Ajax request using any jQuery method:

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

When the user clicks the button and the Ajax request completes successfully, the log message is displayed.

Note: Because .ajaxSuccess() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

All ajaxSuccess handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we 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, we can restrict our callback to only handling events dealing with a particular URL:

$('.log').ajaxSuccess(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxSuccess handler.');
  }
});

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.

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

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

We can attach our event handler to any element:

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

Now, we can make an Ajax request using any jQuery method:

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

When the user clicks the button and the Ajax request completes, the log message is displayed.

Because .ajaxStop() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

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, we can set up a basic Ajax load request:

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

We can attach our event handler to any element:

$('.log').ajaxStart(function() {
  $(this).text('Triggered ajaxStart handler.');
});

Now, we can make an Ajax request using any jQuery method:

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

When the user clicks the button and the Ajax request is sent, the log message is displayed.

Note: Because .ajaxStart() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

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, we can set up a basic Ajax load request:

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

We can attach our event handler to any element:

$('.log').ajaxSend(function() {
  $(this).text('Triggered ajaxSend handler.');
});

Now, we can make an Ajax request using any jQuery method:

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

When the user clicks the button and the Ajax request is about to begin, the log message is displayed.

Note: Because .ajaxSend() is implemented as a method of jQuery instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

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

$('.log').ajaxSend(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxSend handler.');
  }
});

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.

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

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

We can attach our event handler to any element:

$('.log').ajaxError(function() {
  $(this).text('Triggered ajaxError handler.');
});

Now, we can make an Ajax request using any jQuery method:

$('.trigger').click(function() {
  $('.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.

Note: Because .ajaxError() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

All ajaxError handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an ajaxError 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. If the request failed because JavaScript raised an exception, the exception object is passed to the handler as a fourth parameter. For example, we can restrict our callback to only handling events dealing with a particular URL:

$('.log').ajaxError(function(e, xhr, settings, exception) {
  if (settings.url == 'ajax/missing.html') {
    $(this).text('Triggered ajaxError handler.');
  }
});

Any handler that has been attached with .bind() can be removed with .unbind(). In the simplest case, with no arguments, .unbind() removes all handlers attached to the elements:

$('#foo').unbind();

This version removes the handlers regardless of type. To be more precise, we can pass an event type:

$('#foo').unbind('click');

By specifying the click event type, only handlers for that event type will be unbound. This approach can still have negative ramifications if other scripts might be attaching behaviors to the same element, however. Robust and extensible applications typically demand the two-argument version for this reason:

var handler = function() {
  alert('The quick brown fox jumps over the lazy dog.');
};
$('#foo').bind('click', handler);
$('#foo').unbind('click', handler);

By naming the handler, we can be assured that no other functions are caught in the crossfire. Note that the following will not work:

$('#foo').bind('click', function() {
  alert('The quick brown fox jumps over the lazy dog.');
});

$('#foo').unbind('click', function() {
  alert('The quick brown fox jumps over the lazy dog.');
});

Even though the two functions are identical in content, they are created separately and so JavaScript is free to keep them as distinct function objects. To unbind a particular handler, we need a reference to that function and not a different one that happens to do the same thing.

Using Namespaces

Instead of maintaining references to handlers in order to unbind them, we can namespace the events and use this capability to narrow the scope of our unbinding actions. As shown in the discussion for the .bind() method, namespaces are defined by using a period (.) character when binding a handler:

$('#foo').bind('click.myEvents', handler);

When a handler is bound in this fashion, we can still unbind it the normal way:

$('#foo').unbind('click');

However, if we want to avoid affecting other handlers, we can be more specific:

$('#foo').unbind('click.myEvents');

If multiple namespaced handlers are bound, we can unbind them at once:

$('#foo').unbind('click.myEvents.yourEvents');

This syntax is similar to that used for CSS class selectors; they are not hierarchical. This method call is thus the same as:

$('#foo').unbind('click.yourEvents.myEvents');

We can also unbind all of the handlers in a namespace, regardless of event type:

$('#foo').unbind('.myEvents');

It is particularly useful to attach namespaces to event bindings when we are developing plug-ins or otherwise writing code that may interact with other event-handling code in the future.

Using the Event Object

The second form of the .unbind() method is used when we wish to unbind a handler from within itself. For example, suppose we wish to trigger an event handler only three times:

var timesClicked = 0;
$('#foo').bind('click', function(event) {
  alert('The quick brown fox jumps over the lazy dog.');
  timesClicked++;
  if (timesClicked >= 3) {
    $(this).unbind(event);
  }
});

The handler in this case must take a parameter, so that we can capture the event object and use it to unbind the handler after the third click. The event object contains the context necessary for .unbind() to know which handler to remove. This example is also an illustration of a closure. Since the handler refers to the timesClicked variable, which is defined outside the function, incrementing the variable has an effect even between invocations of the handler.

The .bind() method is the primary means of attaching behavior to a document. All JavaScript event types, such as focus, mouseover, and resize, are allowed for eventType. (The beforeunload and error events on the window object use nonstandard conventions and are not supported by jQuery; attach a handler directly to the window object instead.)

The jQuery library provides shortcut methods for binding the standard event types, such as .click() for .bind('click'). A description of each can be found in the discussion of its shortcut method: blur, focus, focusin, focusout, load, resize, scroll, unload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, error

Any string is legal for eventType; if the string is not the name of a native JavaScript 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.

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 a map 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. For example:

function test(){ alert("Hello"); }
$("button").click( test );
$("button").click( test );

The above will generate two alerts when the button is clicked.

The Event object

The handler callback function can also take parameters. When the function is called, the JavaScript 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!

Note that objects are passed to functions by reference, which further complicates this scenario.

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.

See the .trigger() method reference for a way to pass data to a handler at the time the event happens rather than when the handler is bound.

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.

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

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.

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

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').last().css('background-color', 'red');

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

Given a jQuery object that represents a set of DOM elements, the .slice() method constructs a new jQuery object from a subset of the matching elements. The supplied start index identifies the position of one of the elements in the set; if end is omitted, all elements after this one 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>
</ul>

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

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

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

The end parameter allows us to limit the selected range even further. For example:

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

Now only items 3 and 4 are selected. The index is once again zero-based; the range extends up to but not including the specified index.

Negative Indices

The jQuery .slice() method is patterned after the JavaScript .slice() method for arrays. One of the features that it mimics is the ability for negative numbers to be passed as either the start or end parameter. If a negative number is provided, this indicates a position starting from the end of the set, rather than the beginning. For example:

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

This time only list item 4 is turned red, since it is the only item in the range between two from the end (-2) and one from the end (-1).

In the first formulation listed above, jQuery() — which can also be written as $() — searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:

$('div.foo');

Selector Context

By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the $() function. For example, if within a callback function we wish to do a search for an element, we can restrict that search:

$('div.foo').click(function() {
  $('span', this).addClass('bar');
});

Since we've restricted the span selector to the context of this, only spans within the clicked element will get the additional class.

Internally, selector context is implemented with the .find() method, so $('span', this) is equivalent to $(this).find('span').

Using DOM elements

The second and third formulations of this function allow us to create a jQuery object using a DOM element or elements that we have already found in some other way. A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword this:

$('div.foo').click(function() {
  $(this).slideUp();
});

This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the this keyword as a bare DOM element, the element must be wrapped in a jQuery object before we can call jQuery methods on it.

When XML data is returned from an Ajax call, we can use the $() function to wrap it in a jQuery object that we can easily work with. Once this is done, we can retrieve individual elements of the XML structure using .find() and other DOM traversal methods.

Cloning jQuery Objects

When a jQuery object is passed as a parameter to the $() function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.

Returning an Empty Set

As of jQuery 1.4, calling the jQuery() method with no arguments returns an empty jQuery set. In previous versions of jQuery, this would return a set containing the document node.

Creating New Elements

If a string is passed as the parameter to $(), jQuery examines the string to see if it looks like HTML (i.e., it has <tag ... > somewhere within the string). If not, the string is interpreted as a selector expression, as explained above. But if the string appears to be an HTML snippet, jQuery attempts to create new DOM elements as described by the HTML. Then a jQuery object is created and returned that refers to these elements. We can perform any of the usual jQuery methods on this object:

$('<p id="test">My <em>new</em> text</p>').appendTo('body');

When the HTML is more complex than a single tag without attributes, as it is in the above example, the actual creation of the elements is handled by the browser's innerHTML mechanism. Specifically, jQuery creates a new <div> element and sets the innerHTML property of the element to the HTML snippet that was passed in. When the parameter has a single tag, such as $('<img />') or $('<a></a>'), jQuery creates the element using the native JavaScript createElement() function.

To ensure cross-platform compatibility, the snippet must be well-formed. Tags that can contain other elements should be paired with a closing tag:

$('<a href="http://jquery.com"></a>');

Alternatively, jQuery allows XML-like tag syntax (with or without a space before the slash):

$('<a/>');

Tags that cannot contain elements may be quick-closed or not:

$('<img />');
$('<input>');

As of jQuery 1.4, we can pass a map of properties to the second argument. This argument accepts a superset of properties that can be passed to the .attr() method. Furthermore, any event type can be passed in, and the following jQuery methods can be called: val, css, html, text, data, width, height, or offset. Note that Internet Explorer will not allow you to create an input element and change its type; you must specify the type using '<input type="checkbox" />' for example.

This function behaves just like $(document).ready(), in that it should be used to wrap other $() operations on your page that depend on the DOM being ready. While this function is, technically, chainable, there really isn't much use for chaining against it.

When .stop() is called on an element, the currently-running animation (if any) is immediately stopped. If, for instance, an element is being hidden with .slideUp() when .stop() is called, the element will now still be displayed, but will be a fraction of its previous height. Callback functions are not called.

If more than one animation method is called on the same element, the later animations are placed in the effects queue for the element. These animations will not begin until the first one completes. When .stop() is called, the next animation in the queue begins immediately. If the clearQueue parameter is provided with a value of true, then the rest of the animations in the queue are removed and never run.

If the jumpToEnd property is provided with a value of true, the current animation stops, but the element is immediately given its target values for each CSS property. In our above .slideUp() example, the element would be immediately hidden. The callback function is then immediately called, if provided.

The usefulness of the .stop() method is evident when we need to animate an element on mouseenter and mouseleave:

<div id="hoverme">
  Hover me
  <img id="hoverme" src="book.png" alt="" width="100" height="123" />
</div>

We can create a nice fade effect without the common problem of multiple queued animations by adding .stop(true, true) to the chain:

$('#hoverme-stop-2').hover(function() {
  $(this).find('img').stop(true, true).fadeOut();
}, function() {
  $(this).find('img').stop(true, true).fadeIn();
});

Animations may be stopped globally by setting the property $.fx.off to true. When this is done, all animation methods will immediately set elements to their final state when called, rather than displaying an effect.

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 closure—making the program, at least to the eyes of some developers, more readable.

As described in the discussion for .end() above, 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>

If we begin at the third item, we can find the elements which come after it:

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

The result of this call is a red background behind items 3, 4 and 5. 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.

Given a jQuery object that represents a set of DOM elements, the .siblings() method allows us to search through the siblings of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The 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 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>

If we begin at the third item, we can find its siblings:

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

The result of this call is a red background behind items 1, 2, 4, and 5. Since we do not supply a selector expression, all of the siblings are part of the object. If we had supplied one, only the matching items among these four would be included.

The original element is not included among the siblings, which is important to remember when we wish to find all elements at a particular level of the DOM tree.

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

All animated properties should be numeric (except as noted below); 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.) Property values are treated as a number of pixels unless otherwise specified. The units em and % can be specified where applicable.

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.

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 strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

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.

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" 
  style="position: relative; left: 10px;" />

We can 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 we have specified toggle as the target value of the height property. 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 we specified the target value for left as a relative value, the image moves even farther to the right during this second animation.

The position attribute of the element must not be static if we wish to animate the left property as we do in the example.

The jQuery UI project extends the .animate() method by allowing some non-numeric styles such as colors to be animated. The project also includes mechanisms for specifying animations through CSS classes rather than individual attributes.

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, we 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.

We can, for example, 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 map can include the specialEasing property, which is itself a map of CSS properties and their corresponding easing functions. We can 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 plug-in is required for the easeOutBounce function.

Given a jQuery object that represents a set of DOM elements, the .prevAll() method allows us to search through the predecessors of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The 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 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>

If we begin at the third item, we can find the elements which come before it:

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

The result of this call is a red background behind items 1 and 2. Since we do not supply a selector expression, these preceding elements are unequivocally included as part of the object. If we had supplied one, the elements would be tested for a match before they were included.

Given a jQuery object that represents a set of DOM elements, the .prev() method allows us to search through the predecessors of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The 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 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>

If we begin at the third item, we can find the element which comes just before it:

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

The result of this call is a red background behind item 2. Since we do not supply a selector expression, this preceding element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.

The .fadeTo() method animates the opacity of the matched elements.

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 .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.

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').fadeOut('slow', function() {
    // Animation complete.
  });
});

Given a jQuery object that represents a set of DOM elements, the .parents() method allows us to search through the ancestors of these elements in the DOM tree and construct a new jQuery object from the matching elements ordered from immediate parent on up. The .parents() and .parent() methods are similar, except that the latter only travels a single level up the DOM tree.

The 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 item A, we can find its ancestors:

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

The result of this call is a red background for the level-2 list, item II, and the level-1 list (and on up the DOM tree all the way to the <html> element). Since we do not supply a selector expression, all of the ancestors are part of the returned jQuery object. If we had supplied one, only the matching items among these would be included.

The .fadeIn() method animates the opacity of the matched elements.

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.

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 hidden, we can show it slowly:
    $('#clickme').click(function() {
      $('#book').fadeIn('slow', function() {
        // Animation complete
      });
    });

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

The 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 item A, we can find its parents:

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

The result of this call is a red background for the level-2 list. Since we do not supply a selector expression, the parent element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.

Given a jQuery object that represents a set of DOM elements, the .offsetParent() method allows us to search through the ancestors of these elements in the DOM tree and construct a new jQuery object wrapped around the closest positioned ancestor. An element is said to be positioned if it has a CSS position attribute of relative, absolute, or fixed. This information is useful for calculating offsets for performing animations and placing objects on the page.

Consider a page with a basic nested list on it, with a positioned element:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii" style="position: relative;">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 A, we can find its positioned ancestor:

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

This will change the color of list item II, which is positioned.

The .slideToggle() method animates the height of the matched elements. This causes lower parts of the page to slide up or down, appearing to reveal or conceal the items. If the element is initially displayed, it will be hidden; if hidden, it will be shown. The display property is saved and restored as needed. If an element has a display value of inline, then is hidden and shown, it will once again be displayed inline. When the height reaches 0 after a hiding animation, 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.

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" />

We will cause .slideToggle() to be called when another element is clicked:

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

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

A second click will show the element once again:

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  type: 'POST',
  url: url,
  data: data,
  success: success
  dataType: dataType
});

The success callback function is passed the returned data, which will be an XML root element or a text string depending on the MIME type of the response. It is also passed the text status of the response.

As of jQuery 1.4, the success callback function is also passed the XMLHttpRequest object.

Most implementations will specify a success handler:

$.post('ajax/test.html', function(data) {
  $('.result').html(data);
});

This example fetches the requested HTML snippet and inserts it on the page.

Pages fetched with POST are never cached, so the cache and ifModified options in jQuery.ajaxSetup() have no effect on these requests.

The .slideUp() method animates the height of the matched elements. This causes lower parts of the page to slide up, appearing to conceal the items. Once the height reaches 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. If any other string is supplied, or if the duration parameter is omitted, the default duration of 400 milliseconds is used.

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').slideUp('slow', function() {
    // Animation complete.
  });
});
  

Given a jQuery object that represents a set of DOM elements, the .nextAll() method allows us to search through the successors of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The 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 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>

If we begin at the third item, we can find the elements which come after it:

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

The result of this call is a red background behind items 4 and 5. Since we do not supply a selector expression, these following elements are unequivocally included as part of the object. If we had supplied one, the elements would be tested for a match before they were included.

Given a jQuery object that represents a set of DOM elements, the .next() method allows us to search through the immediately following sibling of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the the immediately following sibling matches the selector, it remains in the newly constructed jQuery object; otherwise, it is excluded.

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>

If we begin at the third item, we can find the element which comes just after it:

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

The result of this call is a red background behind item 4. Since we do not supply a selector expression, this following element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.

The .slideDown() method animates the height of the matched elements. This causes lower parts of the page to slide down, making way for the revealed items.

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.

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 hidden, we can show it slowly:

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

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 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.

Unlike in the rest of the tree traversal methods, the selector expression is required in a call to .find(). If we need to retrieve all of the descendant elements, we can pass in the universal selector '*' to accomplish this.

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

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  url: url,
  dataType: 'script',
  success: success
});

The callback is passed the returned JavaScript file. This is generally not useful as the script will already have run at this point.

The script is executed in the global context, so it can refer to other variables and use jQuery functions. Included scripts should have some impact on the current page:

$('.result').html('<p>Lorem ipsum dolor sit amet.</p>');

The script can then be included and run by referencing the file name:

$.getScript('ajax/test.js', function() {
  alert('Load was performed.');
});

Given a jQuery object that represents a set of DOM elements, the .contents() method allows us to search through the 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.

Given a jQuery object that represents a set of DOM elements, the .closest() method allows us to search through these elements and their ancestors in the DOM tree and construct 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 method is primarily meant to be used internally or by plugin authors.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  url: url,
  dataType: 'json',
  data: data,
  success: callback
});

The callback is passed the returned data, which will be a JavaScript object or array as defined by the JSON structure and parsed using the $.parseJSON() method.

Most implementations will specify a success handler:

$.getJSON('ajax/test.json', function(data) {
  $('.result').html('<p>' + data.foo + '</p>'
    + '<p>' + data.baz[1] + '</p>');
});

This example, of course, relies on the structure of the JSON file:

{
  "foo": "The quick brown fox jumps over the lazy dog.",
  "bar": "ABCDEFG",
  "baz": [52, 97]
}

Using this structure, the example inserts the first string and second number from the file onto the page.

Important: As of jQuery 1.4, if the JSON file contains a syntax error, the request will usually fail silently. Avoid frequent hand-editing of JSON data for this reason. JSON is a data-interchange format with syntax rules that are stricter than those of JavaScript's object literal notation. For example, all strings represented in JSON, whether they are properties or values, must be enclosed in double-quotes. For details on the JSON format, see http://json.org/.

JSONP

If the URL includes the string "callback=?" in the URL, the request is treated as JSONP instead. See the discussion of the jsonp data type in $.ajax() for more details.

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.4, the success callback function is also passed the XMLHttpRequest object.

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.

This method is the simplest way to fetch data from the server. It is roughly equivalent to $.get(url, data, success) except that it is a method rather than global function and it has an implicit callback function. When a successful response is detected (i.e. when textStatus is "success" or "notmodified"), .load() sets the HTML contents of the matched element to the returned data. This means that most uses of the method can be quite simple:

$('#result').load('ajax/test.html');

The provided callback, if any, is executed after this post-processing has been performed:

$('#result').load('ajax/test.html', function() {
  alert('Load was performed.');
});

In the two examples above, if the current document does not contain an element with an ID of "result," the .load() method is not executed.

The POST method is used if data is provided as an object; otherwise, GET is assumed.

Note: The event handling suite also has a method named .load(). Which one is fired depends on the set of arguments passed.

Loading Page Fragments

The .load() method, unlike $.get(), allows us to specify a portion of the remote document to be inserted. This is achieved with a special syntax for the url parameter. If one or more space characters are included in the string, the portion of the string following the first space is assumed to be a jQuery selector that determines the content to be loaded.

We could modify the example above to use only part of the document that is fetched:

$('#result').load('ajax/test.html #container');

When this method executes, it retrieves the content of ajax/test.html, but then jQuery parses the returned document to find the element with an ID of container. This element, along with its contents, is inserted into the element with an ID of result, and the rest of the retrieved document is discarded.

jQuery uses the browser's .innerHTML property to parse the retrieved document and insert it into the current document. During this process, browsers often filter elements from the document such as <html>, <title>, or <head> elements. As a result, the elements retrieved by .load() may not be exactly the same as if the document were retrieved directly by the browser.

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, we can implement one of the callback functions.

Callback Functions

The beforeSend, error, dataFilter, success and complete options all take callback functions that are invoked at the appropriate times:

1. beforeSend is called before the request is sent, and is passed the XMLHttpRequest object as a parameter.
2. error is called if the request fails. It is passed the XMLHttpRequest object, a string indicating the error type, and an exception object if applicable.
3. dataFilter is called on success. It is passed the returned data and the value of dataType, and must return the (possibly altered) data to pass on to success.
4. success is called if the request succeeds. It is passed the returned data, a string containing the success code, and the XMLHttpRequest object.
5. complete is called when the request finishes, whether in failure or success. It is passed the XMLHttpRequest object, as well as a string containing the success or error code.

To make use of the returned HTML, we can implement a success handler:

$.ajax({
  url: 'ajax/test.html',
  success: function(data) {
    $('.result').html(data);
    alert('Load was performed.');
  }
});

Such a simple example would generally be better served by using .load() or $.get().

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 XMLHttpRequest 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 the script itself as textual data.

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 JSON.parse() 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 operation is performed using a <script> tag rather than an XMLHttpRequest object. In this case, no XMLHttpRequest object is returned from $.ajax(), nor is one passed to the handler functions such as beforeSend.

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 a map of the form {key1: 'value1', key2: 'value2'}. If the latter form is used, the data is converted into a query string before it is sent. This processing can be circumvented by setting processData to false. The processing might be undesirable if we wish to send an XML object to the server; in this case, we would also want to 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. 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.

The number of elements currently matched. The .size() method will return the same value.

Given a jQuery object that represents a set of DOM elements, the .children() method allows us to search through the immediate children 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 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.

Should be used in conjunction with context to determine the exact query used.

The .live() method for binding event handlers uses this property to determine how to perform its searches. Plug-ins which perform similar tasks may also find the property useful. This property contains a string representing the matched set of elements, but if DOM traversal methods have been called on the object, the string may not be a valid jQuery selector expression. For this reason, the value of .selector is generally most useful immediately following the original creation of the object. Consequently, the .live() method should only be used in this scenario.

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.

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).

The .live() method for binding event handlers uses this property to determine the root element to use for its event delegation needs. Plug-ins which perform similar tasks may also find the property useful.

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.

Given a jQuery object that represents a set of DOM elements, the .not() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; the elements that don't match 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>
</ul>

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

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

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

Removing Specific Elements

The second version of the .not() method allows us to remove elements from the matched set, assuming we have found those elements previously by some other means. For example, suppose our list had an id applied to one of its items:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li id="notli">list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

We can fetch the third list item using the native JavaScript getElementById() function, then remove it from a jQuery object:

$('li').not(document.getElementById('notli'))
  .css('background-color', 'red');

This statement changes the color of items 1, 2, 4, and 5. We could have accomplished the same thing with a simpler jQuery expression, but this technique can be useful when, for example, other libraries provide references to plain DOM nodes.

As of jQuery 1.4, the .not() method can take a function as its argument in the same way that .filter() does. Elements for which the function returns true are excluded from the filtered set; all other elements are included.

Returns the width of the element, along with left and right padding, border, and optionally margin, in pixels.

If includeMargin is omitted or false, the padding and border are included in the calculation; if true, the margin is also included.

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

The top and bottom padding and border are always included in the .outerHeight() calculation; if the includeMargin argument is set to true, the margin (top and bottom) is also included.

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

The .toggle() method binds a handler for the click event, so the rules outlined for the triggering of click apply here as well.

For example, consider the HTML:
<div id="target">
  Click here
</div>

Event handlers can then be bound to the <div>:

$('#target').toggle(function() {
  alert('First handler for .toggle() called.');
}, function() {
  alert('Second handler for .toggle() called.');
});

As the element is clicked repeatedly, the messages alternate:

First handler for .toggle() called.
Second handler for .toggle() called.
First handler for .toggle() called.
Second handler for .toggle() called.
First handler for .toggle() called.

If more than two handlers are provided, .toggle() will cycle among all of them. For example, if there are three handlers, then the first handler will be called on the first click, the fourth click, the seventh click, and so on.

The .toggle() method is provided for convenience. It is relatively straightforward to implement the same behavior by hand, and this can be necessary if the assumptions built into .toggle() prove limiting. For example, .toggle() is not guaranteed to work correctly if applied twice to the same element. Since .toggle() internally uses a click handler to do its work, we must unbind click to remove a behavior attached with .toggle(), so other click handlers can be caught in the crossfire. The implementation also calls .preventDefault() on the event, so links will not be followed and buttons will not be clicked if .toggle() has been called on the element.

$('.target').toggle();

The matched elements will be revealed or hidden immediately, with no animation, by changing the CSS display property. If the element is initially displayed, it will be hidden; if hidden, it will be shown. The display property is saved and restored as needed. If an element has a display value of inline, then is hidden and shown, it will once again be displayed inline.

When a duration is provided, .toggle() becomes an animation method. The .toggle() method animates the width, height, and opacity of the matched elements simultaneously. When these properties reach 0 after a hiding animation, 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.

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" />

We will cause .toggle() to be called when another element is clicked:

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

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

A second click will show the element once again:

The second version of the method accepts a Boolean parameter. If this parameter is true, then the matched elements are shown; if false, the elements are hidden. In essence, the statement:

$('#foo').toggle(showOrHide);
is equivalent to:
if (showOrHide) {
  $('#foo').show();
}
else {
  $('#foo').hide();
}

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.

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 function is used internally to convert form element values into a serialized string representation (See .serialize() for more information).

As of jQuery 1.3, the return value of a function is used instead of the function as a String.

As of jQuery 1.4, the $.param() method serializes deep objects recursively to accommodate modern scripting languages and frameworks such as PHP and Ruby on Rails. You can disable this functionality globally by setting jQuery.ajaxSettings.traditional = true;.

If the object passed is in an Array, it must be an array of objects in the format returned by .serializeArray()

[{name:"first",value:"Rick"},
{name:"last",value:"Astley"},
{name:"job",value:"Rock Star"}]

Note: Because some frameworks have limited ability to parse serialized arrays, we should exercise caution when passing an obj argument that contains objects or arrays nested within another array.

In jQuery 1.4 HTML5 input elements are serialized, as well.

We can display a query string representation of an object and a URI-decoded version of the same as follows:

var myObject = {
  a: {
    one: 1, 
    two: 2, 
    three: 3
  }, 
  b: [1,2,3]
};
var recursiveEncoded = $.param(myObject);
var recursiveDecoded = decodeURIComponent($.param(myObject));

alert(recursiveEncoded);
alert(recursiveDecoded);

The values of recursiveEncoded and recursiveDecoded are alerted as follows:

a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3
a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3

To emulate the behavior of $.param() prior to jQuery 1.4, we can set the traditional argument to true:

var myObject = {
  a: {
    one: 1, 
    two: 2, 
    three: 3
  }, 
  b: [1,2,3]
};
var shallowEncoded = $.param(myObject, true);
var shallowDecoded = decodeURIComponent(shallowEncoded);

alert(shallowEncoded);
alert(shallowDecoded);

The values of shallowEncoded and shallowDecoded are alerted as follows:

a=%5Bobject+Object%5D&b=1&b=2&b=3
a=[object+Object]&b=1&b=2&b=3

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 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.

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 difference between .css(width) and .width() 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 .width() method is recommended when an element's width needs to be used in a mathematical calculation.

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

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

When calling .width('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, any valid CSS measurement may be used for the width (such as 100px, 50%, or auto). Note that in modern browsers, the CSS width property does not include padding, border, or margin.

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

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

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, any valid CSS measurement may be used 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.

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

$('.target').show();

The matched elements will be revealed immediately, with no animation. This is roughly equivalent to calling .css('display', 'block'), except that the display property is restored to whatever it was initially. If an element has a display value of inline, then is hidden and shown, it will once again be displayed inline.

When a duration is provided, .show() becomes an animation method. The .show() method animates the width, height, and opacity of the matched elements simultaneously.

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 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 hidden, we can show it slowly:
$('#clickme').click(function() {
  $('#book').show('slow', function() {
    // Animation complete.
  });
});

The horizontal scroll position is the same as the number of pixels that are hidden from view above the scrollable area. If the scroll bar is at the very left, or if the element is not scrollable, this number will be 0.

The horizontal scroll position is the same as the number of pixels that are hidden from view above the scrollable area. Setting the scrollLeft positions the horizontal scroll of each matched element.

The $.trim() function removes all newlines, spaces (including non-breaking spaces), and tabs from the beginning and end of the supplied string. If these whitespace characters occur in the middle of the string, they are preserved.

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.

$.isArray() returns a Boolean indicating whether the object is a JavaScript array (not an array-like object, such as a jQuery object).

The $.unique() function searches through an array of objects, sorting the array, and removing any duplicate nodes. This function only works on plain JavaScript arrays of DOM elements, and is chiefly used internally by jQuery.

As of jQuery 1.4 the results will always be returned in document order.

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.

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.

The $.map() method applies a function to each item in an array, collecting the results into a new array.

The translation function that is provided to this method is called for each item in the array and is passed two arguments: The item to be translated, and the index within the array.

The function can return:

• the translated value, which will be mapped to the resulting array
• null, to remove the item
• an array of values, which will be flattened into the full array

Map can iterate through Array-like objects, like a jQuery object, that have a length property.

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.

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.

When we supply two or more objects to $.extend(), properties from all of the objects are added to the target object.

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, we 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, we want to preserve both of the original objects, we 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 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.

Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over.

The $.each() function is not the same as .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 a map (JavaScript 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.)

$.each([52, 97], function(index, value) { 
  alert(index + ': ' + value); 
});

This produces two messages:

0: 52
1: 97

If a map is used as the collection, the callback is passed a key-value pair each time:

var map = { 
  'flammable': 'inflammable', 
  'duh': 'no duh' 
}; 
$.each(map, 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.

The vertical scroll position is the same as the number of pixels that are hidden from view above the scrollable area. If the scroll bar is at the very top, or if the element is not scrollable, this number will be 0.

The vertical scroll position is the same as the number of pixels that are hidden from view above the scrollable area. Setting the scrollTop positions the vertical scroll of each matched element.

Rather than using $.browser to detect the current user agent and alter the page presentation based on which browser is running, it is a good practice to perform feature detection. This means that prior to executing code which relies on a browser feature, we test to ensure that the feature works properly. To make this process simpler, jQuery performs many such tests and makes the results available to us as properties of the jQuery.support object.

The values of all the support properties are determined using feature detection (and do not use any form of browser sniffing).

Following are a few resources that explain how feature detection works:

• http://peter.michaux.ca/articles/feature-detection-state-of-the-art-browser-scripting
• http://www.jibbering.com/faq/faq_notes/not_browser_detect.html
• http://yura.thinkweb2.com/cft/

While jQuery includes a number of properties, developers should feel free to add their own as their needs dictate. Many of the jQuery.support properties are rather low-level, so they are most useful for plugin and jQuery core development, rather than general day-to-day development.

The tests included in jQuery.support are as follows:

• boxModel: Is equal to true if the page is rendering according to the W3C CSS Box Model (is currently false in IE 6 and 7 when they are in Quirks Mode). This property is null until document ready occurs.
• cssFloat: Is equal to true if the name of the property containing the CSS float value is .cssFloat, as defined in the CSS Spec. (It is currently false in IE, it uses styleFloat instead).
• hrefNormalized: Is equal to true if the .getAttribute() method retrieves the href attribute of elements unchanged, rather than normalizing it to a fully-qualified URL. (It is currently false in IE, the URLs are normalized).
  DOM l3 spec
• htmlSerialize: Is equal to true if the browser is able to serialize/insert <link> elements using the .innerHTML property of elements. (is currently false in IE).
  HTML5 wd
• leadingWhitespace: Is equal to true if the browser inserts content with .innerHTML exactly as provided—specifically, if leading whitespace characters are preserved. (It is currently false in IE 6-8).
  HTML5 wd
• noCloneEvent: Is equal to true if cloned DOM elements are created without event handlers (that is, if the event handlers on the source element are not cloned). (It is currently false in IE).
  DOM l2 spec
• opacity: Is equal to true if a browser can properly interpret the opacity style property. (It is currently false in IE, it uses alpha filters instead).
  CSS3 spec
• scriptEval: Is equal to true if inline scripts are automatically evaluated and executed when inserted to the document using standard DOM manipulation methods, such as appendChild() and createTextNode(). (It is currently false in IE, it uses .text to insert executable scripts).
  HTML5 WD
• style: Is equal to true if inline styles for an element can be accessed through the DOM attribute called style, as required by the DOM Level 2 specification. In this case, .getAttribute('style') can retrieve this value; in Internet Explorer, .cssText is used for this purpose.
  DOM l2 Style spec
• tbody: Is equal to true if an empty <table> element can exist without a <tbody> element. According to the HTML specification, this sub-element is optional, so the property should be true in a fully-compliant browser. If false, we must account for the possibility of the browser injecting <tbody> tags implicitly. (It is currently false in IE, which automatically inserts tbody if it is not present in a string assigned to innerHTML).
  HTML5 spec