.attr(), .html(), and .val()—also act as "getters," retrieving information from DOM elements for later use.
+ ]]>
\\. For example, an element with id="foo.bar", can use the selector $("#foo\\.bar"). The W3C CSS specification contains the complete set of rules regarding valid CSS selectors. Also useful is the blog entry by Mathias Bynens on CSS character escape sequences for identifiers.
+ To use any of the meta-characters ( such as !"#$%&'()*+,./:;<=>?@[\]^`{|}~ ) as a literal part of a name, it must be escaped with with two backslashes: \\. For example, an element with id="foo.bar", can use the selector $("#foo\\.bar"). The W3C CSS specification contains the complete set of rules regarding valid CSS selectors. Also useful is the blog entry by Mathias Bynens on CSS character escape sequences for identifiers.
<a href="example.html" rel="nofollow">Some text</a> but not <a href="example.html" rel="nofollow foe">Some text</a>.
- Attribute values in selector expressions must follow the rules for W3C CSS selectors; in general, that means anything other than a valid identifier should be surrounded by quotation marks.
+Attribute values in selector expressions must follow the rules for W3C CSS selectors; in general, that means anything other than a valid identifier should be surrounded by quotation marks.
- double quotes inside single quotes:
$('a[rel="nofollow self"]') - single quotes inside double quotes:
$("a[rel='nofollow self']")
@@ -240,7 +306,7 @@
$(selector, context) method.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.
Given a jQuery object that represents a set of DOM elements, the .add() method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to .add() can be pretty much anything that $() accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.
Do not assume that this method appends the elements to the existing collection in the order they are passed to the .add() method. When all elements are members of the same document, the resulting collection from .add() will be sorted in document order; that is, in order of each element's appearance in the document. If the collection consists of elements from different documents or ones not in any document, the sort order is undefined. To create a jQuery object with elements in a well-defined order and without sorting overhead, use the $(array_of_DOM_elements) signature.
The updated set of elements can be used in a following (chained) method, or assigned to a variable for later use. For example:
-
-
-$("p").add("div").addClass("widget");
-var pdiv = $("p").add("div");
-
-
+
+$( "p" ).add( "div" ).addClass( "widget" );
+var pdiv = $( "p" ).add( "div" );
+ The following will not save the added elements, because the .add() method creates a new set and leaves the original set in pdiv unchanged:
-
-var pdiv = $("p");
-pdiv.add("div"); // WRONG, pdiv will not change
-
-
+
+var pdiv = $( "p" );
+pdiv.add( "div" ); // WRONG, pdiv will not change
+ Consider a page with a simple list and a paragraph following it:
-
- <ul>
+
+<ul>
<li>list item 1</li>
<li>list item 2</li>
<li>list item 3</li>
</ul>
-<p>a paragraph</p>
-
+<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');
-
+
+$( "li" ).add( "p" ).css( "background-color", "red" );
+ Or:
-
- $('li').add(document.getElementsByTagName('p')[0])
- .css('background-color', 'red');
-
+
+$( "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');
-
+
+$( "li" ).add( "<p id='new'>new paragraph</p>" )
+ .css( "background-color", "red" );
+ Although the new paragraph has been created and its background color changed, it still does not appear on the page. To place it on the page, we could add one of the insertion methods to the chain.
As of jQuery 1.4 the results from .add() will always be returned in document order (rather than a simple concatenation).
-Note: To reverse the .add() you can use .not( elements | selector ) to remove elements from the jQuery results, or .end() to return to the selection before you added.
Note: To reverse the .add() you can use .not( elements | selector ) to remove elements from the jQuery results, or .end() to return to the selection before you added.
Added this... (notice no border)
+]]>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>
+ <li>list item 1</li>
+ <li>list item 2</li>
+ <li class="third-item">list item 3</li>
+ <li>list item 4</li>
+ <li>list item 5</li>
</ul>
-The result of the following code is a red background behind items 3, 4 and 5:
-$('li.third-item').nextAll().addBack()
- .css('background-color', 'red');
-
+$( "li.third-item" ).nextAll().addBack()
+ .css( "background-color", "red" );
+ First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to .nextAll() then pushes the set of items 4 and 5 onto the stack. Finally, the .addBack() invocation merges these two sets together, creating a jQuery object that points to all three items in document order: {[<li.third-item>,<li>,<li> ]}.
.addBack() method causes the previous set of DOM elements in the traversal stack to be added to the current set. In the first example, the top stack contains the set resulting from .find("p"). In the second example, .addBack() adds the previous set of elements on the stack — in this case $("div.after-addback") — to the current set, selecting both the div and its enclosed paragraphs.Hello
+and
+Goodbye
+]]>.addClass() to add the "green" class to a div that already has a "red" class.Since .after() can accept any number of additional arguments, the same result can be achieved by passing in the three <div>s as three separate arguments, like so: $('p').first().after($newdiv1, newdiv2, existingdiv1). The type and number of arguments will largely depend on the elements that are collected in the code.
Since .after() can accept any number of additional arguments, the same result can be achieved by passing in the three <div>s as three separate arguments, like so: $( "p" ).first().after( $newdiv1, newdiv2, existingdiv1 ). The type and number of arguments will largely depend on the elements that are collected in the code.
This API is deprecated. Use .on( "ajaxComplete", handler ) instead.
"ajaxComplete".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.
This page describes the ajaxComplete event. For the deprecated .ajaxComplete() method, see .ajaxComplete().
Whenever an Ajax request completes, jQuery triggers the ajaxComplete event. Any and all registered ajaxComplete handlers are executed at this time.
To observe this method in action, set up a basic Ajax load request:
-<div class="trigger">Trigger</div>
+
+<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>
-
+ Attach the event handler to the document:
-$(document).ajaxComplete(function() {
+
+$( document ).on( "ajaxComplete", function() {
$( ".log" ).text( "Triggered ajaxComplete handler." );
-});
-
+} );
+ Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).click(function() {
+
+$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
+ When the user clicks the element with class trigger and the Ajax request completes, the log message is displayed.
Note: Because .ajaxComplete() is implemented as a method of jQuery object instances, you can use the this keyword to refer to the selected elements within the callback function. As of jQuery 1.8, however, the .ajaxComplete() method should only be attached to document.
All ajaxComplete handlers are invoked, regardless of what Ajax request was completed. If you must differentiate between the requests, use the parameters passed to the handler. Each time an ajaxComplete handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, you can restrict the callback to only handling events dealing with a particular URL:
$(document).ajaxComplete(function(event, xhr, settings) {
+
+$( document ).on( "ajaxComplete", function( event, xhr, settings ) {
if ( settings.url === "ajax/test.html" ) {
$( ".log" ).text( "Triggered ajaxComplete handler. The result is " +
- xhr.responseHTML );
+ xhr.responseText );
}
-});
- Note: You can get the returned ajax contents by looking at xhr.responseXML or xhr.responseHTML for xml and html respectively.
+} );
+ Note: You can get the returned Ajax contents by looking at xhr.responseText.
This API is deprecated. Use .on( "ajaxError", handler ) instead.
"ajaxError".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.
This page describes the ajaxError event. For the deprecated .ajaxError() method, see .ajaxError().
Whenever an Ajax request completes with an error, jQuery triggers the ajaxError event. Any and all registered ajaxError handlers are executed at this time. Note: This handler is not called for cross-domain script and cross-domain JSONP requests.
To observe this method in action, set up a basic Ajax load request.
-<button class="trigger">Trigger</button>
+
+<button class="trigger">Trigger</button>
<div class="result"></div>
-<div class="log"></div>
+<div class="log"></div>
+ Attach the event handler to the document:
-$(document).ajaxError(function() {
- $( "div.log" ).text( "Triggered ajaxError handler." );
-});
+$( document ).on( "ajaxError", function() {
+ $( ".log" ).text( "Triggered ajaxError handler." );
+} );
+ Now, make an Ajax request using any jQuery method:
-$( "button.trigger" ).click(function() {
+
+$( "button.trigger" ).on( "click", function() {
$( "div.result" ).load( "ajax/missing.html" );
-});
+} );
+ When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.
-Note: Because .ajaxError() is implemented as a method of jQuery object instances, you can use the this keyword within the callback function to refer to the selected elements. As of jQuery 1.8, however, the .ajaxError() method should only be attached to document.
All ajaxError handlers are invoked, regardless of what Ajax request was completed. To differentiate between the requests, use the parameters passed to the handler. Each time an ajaxError handler is executed, it is passed the event object, the jqXHR object (prior to jQuery 1.5, the XHR object), and the settings object that was used in the creation of the request. If the request failed because JavaScript raised an exception, the exception object is passed to the handler as a fourth parameter. For example, to restrict the error callback to only handling events dealing with a particular URL:
$( document ).ajaxError(function(event, jqxhr, settings, exception) {
+ All ajaxError handlers are invoked, regardless of what Ajax request was completed. To differentiate between the requests, use the parameters passed to the handler. Each time an ajaxError handler is executed, it is passed the event object, the jqXHR object (prior to jQuery 1.5, the XHR object), and the settings object that was used in the creation of the request. When an HTTP error occurs, the fourth argument (thrownError) receives the textual portion of the HTTP status, such as "Not Found" or "Internal Server Error." For example, to restrict the error callback to only handling events dealing with a particular URL:
+
+$( document ).on( "ajaxError", function( event, jqxhr, settings, thrownError ) {
if ( settings.url == "ajax/missing.html" ) {
$( "div.log" ).text( "Triggered ajaxError handler." );
}
-});
+} );
+ This API is deprecated. Use .on( "ajaxSend", handler ) instead.
"ajaxSend".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.
This page describes the ajaxSend event. For the deprecated .ajaxSend() method, see .ajaxSend().
Whenever an Ajax request is about to be sent, jQuery triggers the ajaxSend event. Any and all registerd ajaxSend handlers are executed at this time.
To observe this method in action, set up a basic Ajax load request:
-<div class="trigger">Trigger</div>
+
+<div class="trigger">Trigger</div>
<div class="result"></div>
-<div class="log"></div>
+<div class="log"></div>
+ Attach the event handler to the document:
-$(document).ajaxSend(function() {
+
+$( document ).on( "ajaxSend", function() {
$( ".log" ).text( "Triggered ajaxSend handler." );
-});
+} );
+ Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).click(function() {
+
+$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
+ When the user clicks the element with class trigger and the Ajax request is about to begin, the log message is displayed.
Note: Because .ajaxSend() is implemented as a method of jQuery instances, you can use the this keyword to refer to the selected elements within the callback function. As of jQuery 1.8, however, the .ajaxSend() method should only be attached to document.
All ajaxSend handlers are invoked, regardless of what Ajax request is to be sent. If you must differentiate between the requests, use the parameters passed to the handler. Each time an ajaxSend handler is executed, it is passed the event object, the jqXHR object (in version 1.4, XMLHttpRequestobject), and the settings object that was used in the creation of the Ajax request. For example, you can restrict the callback to only handling events dealing with a particular URL:
$(document).ajaxSend(function(event, jqxhr, settings) {
+ All ajaxSend handlers are invoked, regardless of what Ajax request is to be sent. If you must differentiate between the requests, use the parameters passed to the handler. Each time an ajaxSend handler is executed, it is passed the event object, the jqXHR object (in version 1.4, XMLHttpRequestobject), and the settings object that was used in the creation of the Ajax request. For example, you can restrict the callback to only handling events dealing with a particular URL:
+
+$( document ).on( "ajaxSend", function( event, jqxhr, settings ) {
if ( settings.url == "ajax/test.html" ) {
$( ".log" ).text( "Triggered ajaxSend handler." );
}
-});
+} );
+ This API is deprecated. Use .on( "ajaxStart", handler ) instead.
"ajaxStart".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.
This page describes the ajaxStart event. For the deprecated .ajaxStart() method, see .ajaxStart().
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 .on( "ajaxStart", ... ) are executed at this time.
To observe this method in action, set up a basic Ajax load request:
-<div class="trigger">Trigger</div>
+
+<div class="trigger">Trigger</div>
<div class="result"></div>
-<div class="log"></div>
+<div class="log"></div>
+ Attach the event handler to any element:
-$(document).ajaxStart(function() {
+
+$( document ).on( "ajaxStart", function() {
$( ".log" ).text( "Triggered ajaxStart handler." );
-});
+} );
+ Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).click(function() {
- $( ".result" ).load("ajax/test.html");
-});
+$( ".trigger" ).on( "click", function() {
+ $( ".result" ).load( "ajax/test.html" );
+} );
+ When the user clicks the element with class trigger and the Ajax request is sent, the log message is displayed.
Note: Because .ajaxStart() is implemented as a method of jQuery object instances, you can use the this keyword to refer to the selected elements within the callback function. As of jQuery 1.8, however, the .ajaxStart() method should only be attached to document.
This API is deprecated. Use .on( "ajaxStop", handler ) instead.
"ajaxStop".Whenever an Ajax request completes, jQuery checks whether there are any other outstanding Ajax requests. If none remain, jQuery triggers the ajaxStop event. Any and all handlers that have been registered with the .ajaxStop() method are executed at this time. The ajaxStop event is also triggered if the last outstanding Ajax request is cancelled by returning false within the beforeSend callback function.
This page describes the ajaxStop event. For the deprecated .ajaxStop() method, see .ajaxStop().
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 registered ajaxStop handlers are executed at this time. The ajaxStop event is also triggered if the last outstanding Ajax request is cancelled by returning false within the beforeSend callback function.
To observe this method in action, set up a basic Ajax load request:
-<div class="trigger">Trigger</div>
+
+<div class="trigger">Trigger</div>
<div class="result"></div>
-<div class="log"></div>
+<div class="log"></div>
+ Attach the event handler to the document:
-$( ".log" ).ajaxStop(function() {
- $(this).text( "Triggered ajaxStop handler." );
-});
+$( document ).on( "ajaxStop", function() {
+ $( ".log" ).text( "Triggered ajaxStop handler." );
+} );
+ Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).click(function() {
+
+$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
+ When the user clicks the element with class trigger and the Ajax request completes, the log message is displayed.
Because .ajaxStop() is implemented as a method of jQuery object instances, you can use the this keyword to refer to the selected elements within the callback function. As of jQuery 1.8, however, the .ajaxStop() method should only be attached to document.
This API is deprecated. Use .on( "ajaxSuccess", handler ) instead.
"ajaxSuccess".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.
This page describes the ajaxSuccess event. For the deprecated .ajaxSuccess() method, see .ajaxSuccess().
Whenever an Ajax request completes successfully, jQuery triggers the ajaxSuccess event. Any and all registered ajaxSuccess handlers are executed at this time.
To observe this method in action, set up a basic Ajax load request:
-<div class="trigger">Trigger</div>
+
+<div class="trigger">Trigger</div>
<div class="result"></div>
-<div class="log"></div>
+<div class="log"></div>
+ Attach the event handler to any element:
-$(document).ajaxSuccess(function() {
+
+$( document ).on( "ajaxSuccess", function() {
$( ".log" ).text( "Triggered ajaxSuccess handler." );
-});
+} );
+ Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).on("click", function() {
+
+$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
+ When the user clicks the element with class trigger and the Ajax request completes successfully, the log message is displayed.
Note: Because .ajaxSuccess() is implemented as a method of jQuery object instances, use the this keyword to refer to the selected elements within the callback function. As of jQuery 1.8, however, the .ajaxSuccess() method should only be attached to document.
All ajaxSuccess handlers are invoked, regardless of what Ajax request was completed. If you must differentiate between the requests, you can use the parameters passed to the handler. Each time an ajaxSuccess handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, you can restrict the callback to only handling events dealing with a particular URL:
$(document).ajaxSuccess(function(event, xhr, settings) {
+
+$( document ).on( "ajaxSuccess", function( event, xhr, settings ) {
if ( settings.url == "ajax/test.html" ) {
- $( ".log" ).text( "Triggered ajaxSuccess handler. The ajax response was: " +
- xhr.responseText );
+ $( ".log" ).text( "Triggered ajaxSuccess handler. The Ajax response was: " +
+ xhr.responseText );
}
-});
- Note: You can get the returned ajax contents by looking at xhr.responseXML or xhr.responseText for xml and html respectively.
+} );
+ Note: You can get the returned Ajax contents by looking at xhr.responseXML or xhr.responseText for xml and html respectively.
<script> or <link> element into the DOM, that element will be counted as well.Note: This function has been deprecated and is now an alias for .addBack(), which should be used with jQuery 1.8 and later.
As described in the discussion for .end(), jQuery objects maintain an internal stack that keeps track of changes to the matched set of elements. When one of the DOM traversal methods is called, the new set of elements is pushed onto the stack. If the previous set of elements is desired as well, .andSelf() can help.
Consider a page with a simple list on it:
-
-<ul>
- <li>list item 1</li>
- <li>list item 2</li>
- <li class="third-item">list item 3</li>
- <li>list item 4</li>
- <li>list item 5</li>
-</ul>
-The result of the following code is a red background behind items 3, 4 and 5:
-$('li.third-item').nextAll().andSelf()
- .css('background-color', 'red');
-First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to .nextAll() then pushes the set of items 4 and 5 onto the stack. Finally, the .andSelf() invocation merges these two sets together, creating a jQuery object that points to all three items in document order: {[<li.third-item>,<li>,<li> ]}.
Note: This API has been removed in jQuery 3.0; use .addBack() instead, which should work identically.
.andSelf() method causes the previous set of DOM elements in the traversal stack to be added to the current set. In the first example, the top stack contains the set resulting from .find("p"). In the second example, .andSelf() adds the previous set of elements on the stack — in this case $("div.after-andself") — to the current set, selecting both the div and its enclosed paragraphs.The .animate() method allows us to create animation effects on any numeric CSS property. The only required parameter is a plain object of CSS properties. This object is similar to the one that can be sent to the .css() method, except that the range of properties is more restrictive.
Animation Properties and Values
-All animated properties should be animated to a single numeric value, except as noted below; most properties that are non-numeric cannot be animated using basic jQuery functionality (For example, width, height, or left can be animated but background-color cannot be, unless the jQuery.Color() plugin is used). Property values are treated as a number of pixels unless otherwise specified. The units em and % can be specified where applicable.
All animated properties should be animated to a single numeric value, except as noted below; most properties that are non-numeric cannot be animated using basic jQuery functionality (For example, width, height, or left can be animated but background-color cannot be, unless the jQuery.Color plugin is used). Property values are treated as a number of pixels unless otherwise specified. The units em and % can be specified where applicable.
In addition to style properties, some non-style properties such as scrollTop and scrollLeft, as well as custom properties, can be animated.
Shorthand CSS properties (e.g. font, background, border) are not fully supported. For example, if you want to animate the rendered border width, at least a border style and border width other than "auto" must be set in advance. Or, if you want to animate font size, you would use fontSize or the CSS equivalent 'font-size' rather than simply 'font'.
In addition to numeric values, each property can take the strings 'show', 'hide', and 'toggle'. These shortcuts allow for custom hiding and showing animations that take into account the display type of the element.
In addition to numeric values, each property can take the strings 'show', 'hide', and 'toggle'. These shortcuts allow for custom hiding and showing animations that take into account the display type of the element. In order to use jQuery's built-in toggle state tracking, the 'toggle' keyword must be consistently given as the value of the property being animated.
Animated properties can also be relative. If a value is supplied with a leading += or -= sequence of characters, then the target value is computed by adding or subtracting the given number from the current value of the property.
-+Note: Unlike shorthand animation methods such as
-.slideDown()and.fadeIn(), the.animate()method does not make hidden elements visible as part of the effect. For example, given$('someElement').hide().animate({height:'20px'}, 500), the animation will run, but the element will remain hidden.
Note: Unlike shorthand animation methods such as .slideDown() and .fadeIn(), the .animate() method does not make hidden elements visible as part of the effect. For example, given $( "someElement" ).hide().animate({height: "20px"}, 500), the animation will run, but the element will remain hidden.
Duration
Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The default duration is 400 milliseconds. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.
Complete Function
-If supplied, the complete callback function is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, the callback is executed once per matched element, not once for the animation as a whole.
Callback Functions
+If supplied, the start, step, progress, complete, done, fail, and always callbacks are called on a per-element basis; this is set to the DOM element being animated. If no elements are in the set, no callbacks are called. If multiple elements are animated, the callback is executed once per matched element, not once for the animation as a whole. Use the .promise() method to obtain a promise to which you can attach callbacks that fire once for an animated set of any size, including zero elements.
Basic Usage
To animate any element, such as a simple image:
-<div id="clickme">
+
+<div id="clickme">
Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123"
- style="position: relative; left: 10px;" />
+ style="position: relative; left: 10px;">
+ To animate the opacity, left offset, and height of the image simultaneously:
-$('#clickme').click(function() {
- $('#book').animate({
+
+$( "#clickme" ).on( "click", function() {
+ $( "#book" ).animate({
opacity: 0.25,
- left: '+=50',
- height: 'toggle'
+ left: "+=50",
+ height: "toggle"
}, 5000, function() {
// Animation complete.
});
});
-
+
- 
+
+
Note that the target value of the height property is 'toggle'. Since the image was visible before, the animation shrinks the height to 0 to hide it. A second click then reverses this transition:
-
- 
+
+
The opacity of the image is already at its target value, so this property is not animated by the second click. Since the target value for left is a relative value, the image moves even farther to the right during this second animation.
Directional properties (top, right, bottom, left) have no discernible effect on elements if their position style property is static, which it is by default.
--Note: 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.
-+Note: if attempting to animate an element with a height or width of 0px, where contents of the element are visible due to overflow, jQuery may clip this overflow during animation. By fixing the dimensions of the original element being hidden however, it is possible to ensure that the animation runs smoothly. A clearfix can be used to automatically fix the dimensions of your main element without the need to set this manually.
-
Note: 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.
Note: if attempting to animate an element with a height or width of 0px, where contents of the element are visible due to overflow, jQuery may clip this overflow during animation. By fixing the dimensions of the original element being hidden however, it is possible to ensure that the animation runs smoothly. A clearfix can be used to automatically fix the dimensions of your main element without the need to set this manually.
+Step Function
-The second version of .animate() provides a step option — a callback function that is fired at each step of the animation. This function is useful for enabling custom animation types or altering the animation as it is occurring. It accepts two arguments (now and fx), and this is set to the DOM element being animated.
-
The second version of .animate() provides a step option — a callback function that is fired at each step of the animation. This function is useful for enabling custom animation types or altering the animation as it is occurring. It accepts two arguments (now and fx), and this is set to the DOM element being animated.
now: the numeric value of the property being animated at each stepfx: a reference to thejQuery.fxprototype object, which contains a number of properties such aselemfor the animated element,startandendfor the first and last value of the animated property, respectively, andpropfor the property being animated.
Note that the step function is called for each animated property on each animated element. For example, given two list items, the step function fires four times at each step of the animation:
$('li').animate({
+
+$( "li" ).animate({
opacity: .5,
- height: '50%'
-},
-{
- step: function(now, fx) {
- var data = fx.elem.id + ' ' + fx.prop + ': ' + now;
- $('body').append('<div>' + data + '</div>');
+ height: "50%"
+}, {
+ step: function( now, fx ) {
+ var data = fx.elem.id + " " + fx.prop + ": " + now;
+ $( "body" ).append( "<div>" + data + "</div>" );
}
-});
+});
+ Easing
-The remaining parameter of .animate() is a string naming an easing function to use. An easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.
The remaining parameter of .animate() is a string naming an easing function to use. An easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.
Per-property Easing
As of jQuery version 1.4, you can set per-property easing functions within a single .animate() call. In the first version of .animate(), each property can take an array as its value: The first member of the array is the CSS property and the second member is an easing function. If a per-property easing function is not defined for a particular property, it uses the value of the .animate() method's optional easing argument. If the easing argument is not defined, the default swing function is used.
For example, to simultaneously animate the width and height with the swing easing function and the opacity with the linear easing function:
$('#clickme').click(function() {
- $('#book').animate({
- width: ['toggle', 'swing'],
- height: ['toggle', 'swing'],
- opacity: 'toggle'
- }, 5000, 'linear', function() {
- $(this).after('<div>Animation complete.</div>');
+
+$( "#clickme" ).on( "click", function() {
+ $( "#book" ).animate({
+ width: [ "toggle", "swing" ],
+ height: [ "toggle", "swing" ],
+ opacity: "toggle"
+ }, 5000, "linear", function() {
+ $( this ).after( "<div>Animation complete.</div>" );
});
-});
+});
+ In the second version of .animate(), the options object can include the specialEasing property, which is itself an object of CSS properties and their corresponding easing functions. For example, to simultaneously animate the width using the linear easing function and the height using the easeOutBounce easing function:
$('#clickme').click(function() {
- $('#book').animate({
- width: 'toggle',
- height: 'toggle'
+
+$( "#clickme" ).on( "click", function() {
+ $( "#book" ).animate({
+ width: "toggle",
+ height: "toggle"
}, {
duration: 5000,
specialEasing: {
- width: 'linear',
- height: 'easeOutBounce'
+ width: "linear",
+ height: "easeOutBounce"
},
complete: function() {
- $(this).after('<div>Animation complete.</div>');
+ $( this ).after( "<div>Animation complete.</div>" );
}
});
-});
+});
+ As previously noted, a plugin is required for the easeOutBounce function.