Plugins Contribute Events Support JS Foundation

Support the JS Foundation

Download API Documentation log Plugin rower upport Search

Ajax
Global Ajax Event Handlers
.animate()
Helper Functions Categories: Effects > Custom

Low-Level Interface
.animate( propertie [, duration ] [, eaing ] [, complete ] ) Return: jQuer
Shorthand Methods

Description: Perform a custom animation of a set of CSS properties.

Attributes

Callbacks Object  .animate( propertie [, duration ] [, eaing ] [, complete ] ) verion added: 1.0

Core properties
CSS Type: PlainObject
An object of CSS properties and values that the animation will move toward.
Data
duration (default: 400 )
Deferred Object
Type: Number or String
Deprecated A string or number determining how long the animation will run.
Deprecated 1.3
easing (default: wing )
Deprecated 1.7 Type: String
A string indicating which easing function to use for the transition.
Deprecated 1.8

Deprecated 1.9 complete

Function()
Type: Function ()
Deprecated 1.10 A function to call once the animation is complete, called once per matched element.
Deprecated 3.0
 .animate( propertie, option ) verion added: 1.0
Deprecated 3.3
properties
Type: PlainObject
Dimensions An object of CSS properties and values that the animation will move toward.
Effects
options
Basics
Type: PlainObject
Custom A map of additional options to pass to the method.

Fading duration (default: 400 )

Type: Number or String
Sliding A string or number determining how long the animation will run.

Events easing (default: wing )

Type: String
Browser Events A string indicating which easing function to use for the transition.
Document Loading
queue (default: true )
Event Handler Attachment Type: Boolean or String
A Boolean indicating whether to place the animation in the effects queue. If false, the animation will
Event Object
begin immediately. As of jQuery 1.7,
1.7, the queue option can also accept a string, in which case the
Form Events animation is added to the queue represented by that string. When a custom queue name is used the
animation does not automatically start; you must call .dequeue("queuename") to start it.
Keyboard Events

Mouse Events specialEasing

Type: PlainObject
An object containing one or more of the CSS properties defined by the properties argument and their
Forms corresponding easing functions. (version added: 1.4)
1.4)
Internals
step
Manipulation Function(( Number now, Tween tween )
Type: Function
Class Attribute A function to be called for each animated property of each animated element. This function provides an
opportunity to modify the Tween object to change the value of the property before it is set.
Copying
progress
DOM Insertion, Around
Function(( Promise animation, Number progress, Number remainingMs )
Type: Function
DOM Insertion, Inside A function to be called after each step of the animation, only once per animated element regardless of
the number of animated properties. (version added: 1.8) 1.8)
DOM Insertion, Outside

DOM Removal complete

Function()
Type: Function ()
DOM Replacement A function that is called once the animation on an element is complete.
General Attributes
start
Style Properties Function(( Promise animation )
Type: Function
A function to call when the animation on an element begins. (version added: 1.8
1.8))

Miscellaneous
done
Collection Manipulation Function(( Promise animation, Boolean jumpedToEnd )
Type: Function
A function to be called when the animation on an element completes (its Promise object is resolved).
Data Storage
(version added: 1.8
1.8))
DOM Element Methods
fail
Setup Methods
Function(( Promise animation, Boolean jumpedToEnd )
Type: Function
 A function to be called when the animation on an element fails to complete (its Promise object is
Offset rejected). (version added: 1.8
1.8))

Properties
Properties of jQuery Object Instances
Properties of the Global jQuery Object
always
Function(( Promise animation, Boolean jumpedToEnd )
Type: Function
A function to be called when the animation on an element completes or stops without completing (its
Promise object is either resolved or rejected). (version added: 1.8
1.8))

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

Basic Animation Propertie and Value

Basic Filter All animated properties should be animated to a single numeric value, except as noted below; most properties that are non-
Child Filter numeric cannot be animated using basic jQuery functionality (For example, width , height , or left can be animated but
ackground-color cannot be, unless the jQuery.Color plugin is used). Property values are treated as a number of pixels
Content Filter
unless otherwise specified. The units em and % can be specified where applicable.
Form
In addition to style properties, some non-style properties such as crollTop and crollLeft , as well as custom properties,
Hierarchy can be animated.
jQuery Extensions
Shorthand CSS properties (e.g. font, background, border) are not fully supported. For example, if you want to animate the
Visibility Filter 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 fontize or the CSS equivalent 'font-ize' rather than simply 'font' .

Traversing In addition to numeric values, each property can take the strings 'how' , 'hide' , and 'toggle' . These shortcuts allow for
Filtering 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.
Miscellaneous Traversing

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

Utilities
Note: Unlike shorthand animation methods such as .lideDown() and .fadeIn() , the .animate() method does
Version not make hidden elements visible as part of the effect. For example, given $( "omelement"
Version 1.0 ).hide().animate({height: "20px"}, 500) , the animation will run, but the element will remain hidden.

Version 1.0.4
Duration
Version 1.1

Version 1.1.2 Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The default duration is 400
milliseconds. The strings 'fat' and 'low' can be supplied to indicate durations of 200 and 600 milliseconds,
Version 1.1.3 respectively.
Version 1.1.4
Callack Function
Version 1.2
If supplied, the tart , tep , progre , complete , done , fail , and alwa callbacks are called on a per-element basis;
Version 1.2.3 thi is set to the DOM element being animated. If no elements are in the set, no callbacks are called. If multiple elements are
Version 1.2.6 animated, the callback is executed once per matched element, not once for the animation as a whole. Use the .promie()
method to obtain a promise to which you can attach callbacks that fire once for an animated set of any size, including zero
Version 1.3
elements.
Version 1.4
aic Uage
Version 1.4.1
To animate any element, such as a simple image:
Version 1.4.2

Version 1.4.3 1 <div id="clickme">

2 Click here
Version 1.4.4 3 </div>
4 <img id="ook" rc="ook.png" alt="" width="100" height="123"
Version 1.5 5 tle="poition: relative; left: 10px;">
Version 1.5.1
To animate the opacity, left offset, and height of the image simultaneously:
Version 1.6

Version 1.7 1 $( "#clickme" ).click(function() {

2 $( "#ook" ).animate({
Version 1.8 3 opacit: 0.25,
4 left: "+=50",
Version 1.9 5 height: "toggle"
6 }, 5000, function() {
Version 1.12 & 2.2 7 // Animation complete.
8 });
Version 3.0 9 });
Version 3.1

Figure 1 - Illutration of the pecified animation effect

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:
 Figure 2 - Illutration of the pecified animation effect

The opacit 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 , ottom , left ) have no discernible effect on elements if their poition style property is
tatic , 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.

tep Function

The second version of .animate() provides a tep 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 thi is set to the DOM element being animated.

now : the numeric value of the property being animated at each step

fx : a reference to the jQuer.fx prototype object, which contains a number of properties such as elem for the
animated element, tart and end for the first and last value of the animated property, respectively, and prop for the
property being animated.

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

1 $( "li" ).animate({
2 opacit: .5,
3 height: "50%"
4 }, {
5 tep: function( now, fx ) {
6 var data = fx.elem.id + " " + fx.prop + ": " + now;
7 $( "od" ).append( "<div>" + data + "</div>" );
8 }
9 });

aing

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 wing , 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-propert aing

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 wing function is used.

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

1 $( "#clickme" ).click(function() {
2 $( "#ook" ).animate({
3 width: [ "toggle", "wing" ],
4 height: [ "toggle", "wing" ],
5 opacit: "toggle"
6 }, 5000, "linear", function() {
7 $( thi ).after( "<div>Animation complete.</div>" );
8 });
9 });

In the second version of .animate() , the options object can include the pecialaing 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 eaeOutounce easing function:

1 $( "#clickme" ).click(function() {
2 $( "#ook" ).animate({
3 width: "toggle",
4 height: "toggle"
5 }, {
6 duration: 5000,
7 pecialaing: {
8 width: "linear",
9 height: "eaeOutounce"
10 },
11 complete: function() {
12 $( thi ).after( "<div>Animation complete.</div>" );
13 }
14 });
15 });

As previously noted, a plugin is required for the eaeOutounce function.

Additional Note:
All jQuery effects, including .animate() , can be turned off globally by setting jQuer.fx.off = true , which
effectively sets the duration to 0. For more information, see jQuery.fx.off.
xample:
Click the button to animate the div with a number of different properties.

1 <!doctpe html>
2 <html lang="en">
3 <head>
4 <meta charet="utf-8">
5 <title>animate demo</title>
6 <tle>
7 div {
8 ackground-color: #ca;
9 width: 100px;
10 order: 1px olid green;
11 }
12 </tle>
13 <cript rc="http://code.jquer.com/jquer-1.10.2.j"></cript>
14 </head>
15 <od>
16
17 <utton id="go">&raquo; Run</utton>
18 <div id="lock">Hello!</div>
19
20 <cript>
21 // Uing multiple unit tpe within one animation.
22
23 $( "#go" ).click(function() {
24 $( "#lock" ).animate({
25 width: "70%",
26 opacit: 0.4,
27 marginLeft: "0.6in",
28 fontize: "3em",
29 orderWidth: "10px"
30 }, 1500 );
31 });
32 </cript>
33
34 </od>
35 </html>

Demo:

Animates a div's left property with a relative value. Click several times on the buttons to see the relative animations queued up.

1 <!doctpe html>
2 <html lang="en">
3 <head>
4 <meta charet="utf-8">
5 <title>animate demo</title>
6 <tle>
7 div {
8 poition: aolute;
9 ackground-color: #ac;
10 left: 50px;
11 width: 90px;
12 height: 90px;
13 margin: 5px;
14 }
15 </tle>
16 <cript rc="http://code.jquer.com/jquer-1.10.2.j"></cript>
17 </head>
18 <od>
19
20 <utton id="left">&laquo;</utton>
21 <utton id="right">&raquo;</utton>
22 <div cla="lock"></div>
23
24 <cript>
25 $( "#right" ).click(function() {
26 $( ".lock" ).animate({ "left": "+=50px" }, "low" );
27 });
28
29 $( "#left" ).click(function(){
30 $( ".lock" ).animate({ "left": "-=50px" }, "low" );
31 });
32 </cript>
33
34 </od>
35 </html>

Demo:
The first button shows how an unqueued animation works. It expands the div out to 90% width while the font-size is increasing.
Once the font-size change is complete, the border animation will begin. The second button starts a traditional chained
animation, where each animation will start once the previous animation on the element has completed.

1 <!doctpe html>
2 <html lang="en">
3 <head>
4 <meta charet="utf-8">
5 <title>animate demo</title>
6 <tle>
7 div {
8 ackground-color: #ca;
9 width: 200px;
10 height: 1.1em;
11 text-align: center;
12 order: 2px olid green;
13 margin: 3px;
14 font-ize: 14px;
15 }
16 utton {
17 font-ize: 14px;
18 }
19 </tle>
20 <cript rc="http://code.jquer.com/jquer-1.10.2.j"></cript>
21 </head>
22 <od>
23
24 <utton id="go1">&raquo; Animate lock1</utton>
25 <utton id="go2">&raquo; Animate lock2</utton>
26 <utton id="go3">&raquo; Animate oth</utton>
27 <utton id="go4">&raquo; Reet</utton>
28 <div id="lock1">lock1</div>
29 <div id="lock2">lock2</div>
30
31 <cript>
32 $( "#go1" ).click(function() {
33 $( "#lock1" )
34 .animate({
35 width: "90%"
36 }, {
37 queue: fale,
38 duration: 3000
39 })
40 .animate({ fontize: "24px" }, 1500 )
41 .animate({ orderRightWidth: "15px" }, 1500 );
42 });
43
44 $( "#go2" ).click(function() {
45 $( "#lock2" )
46 .animate({ width: "90%" }, 1000 )
47 .animate({ fontize: "24px" }, 1000 )
48 .animate({ orderLeftWidth: "15px" }, 1000 );
49 });
50
51 $( "#go3" ).click(function() {
52 $( "#go1" ).add( "#go2" ).click();
53 });
54
55 $( "#go4" ).click(function() {
56 $( "div" ).c({
57 width: "",
58 fontize: "",
59 orderWidth: ""
60 });
61 });
62 </cript>
63
64 </od>
65 </html>

Demo:

Animates the first div's left property and synchronizes the remaining divs, using the step function to set their left properties at
each stage of the animation.
 1 <!doctpe html>
2 <html lang="en">
3 <head>
4 <meta charet="utf-8">
5 <title>animate demo</title>
6 <tle>
7 div {
8 poition: relative;
9 ackground-color: #ac;
10 width: 40px;
11 height: 40px;
12 float: left;
13 margin: 5px;
14 }
15 </tle>
16 <cript rc="http://code.jquer.com/jquer-1.10.2.j"></cript>
17 </head>
18 <od>
19
20 <p><utton id="go">Run »</utton></p>
21 <div cla="lock"></div>
22 <div cla="lock"></div>
23 <div cla="lock"></div>
24 <div cla="lock"></div>
25 <div cla="lock"></div>
26 <div cla="lock"></div>
27
28 <cript>
29 $( "#go" ).click(function() {
30 $( ".lock:firt" ).animate({
31 left: 100
32 }, {
33 duration: 1000,
34 tep: function( now, fx ){
35 $( ".lock:gt(0)" ).c( "left", now );
36 }
37 });
38 });
39 </cript>
40
41 </od>
42 </html>

Demo:

Animate all paragraphs to toggle both height and opacity, completing the animation within 600 milliseconds.

1 $( "p" ).animate({
2 height: "toggle",
3 opacit: "toggle"
4 }, "low" );

Animate all paragraphs to a left style of 50 and opacity of 1 (opaque, visible), completing the animation within 500 milliseconds.

1 $( "p" ).animate({
2 left: 50,
3 opacit: 1
4 }, 500 );

Animate the left and opacity style properties of all paragraphs; run the animation outside the queue, so that it will automatically
start without waiting for its turn.

1 $( "p" ).animate({
2 left: "50px",
3 opacit: 1
4 }, {
5 duration: 500,
6 queue: fale
7 });

An example of using an 'easing' function to provide a different style of animation. This will only work if you have a plugin that
provides this easing function. Note, this code will do nothing unless the paragraph element is hidden.

1 $( "p" ).animate({
2 opacit: "how"
3 }, "low", "eaein" );

Animates all paragraphs to toggle both height and opacity, completing the animation within 600 milliseconds.

1 $( "p" ).animate({
2 height: "toggle",
3 opacit: "toggle"
4 }, {
5 duration: "low"
6 });

Use an easing function to provide a different style of animation. This will only work if you have a plugin that provides this easing
function.
 1 $( "p" ).animate({
2 opacit: "how"
3 }, {
4 duration: "low",
5 eaing: "eaein"
6 });

Animate all paragraphs and execute a callback function when the animation is complete. The first argument is an object of CSS
properties, the second specifies that the animation should take 1000 milliseconds to complete, the third states the easing type,
and the fourth argument is an anonymous callback function.

1 $( "p" ).animate({
2 height: 200,
3 width: 400,
4 opacit: 0.5
5 }, 1000, "linear", function() {
6 alert( "all done" );
7 });

OOK

Learning jQuery Fourth Edition jQuery in Action jQuery Succinctly

Karl Swedberg and Jonathan Chaffer Bear Bibeault, Yehuda Katz, and Aurelio Cody Lindley
De Rosa

Copyright 2018 The jQuery Foundation. jQuery License

 Learning Center  Forum  API  Twitter  IRC  GitHub
Web hosting by Digital Ocean | CDN by StackPath