.animate() JQ Home  <<  Effects  <<  .animate()

Custom animation.

Description

The .animate() method is used to perform a custom animation for a set of CSS properties.

  • The .animate() method does not make hidden elements visible as part of the effect. The animation will still run, but the element will remain hidden.
  • When hiding elements the display property of the elements to be hidden is stored in the jQuery cache, so if the element is later made visible, the display property is restored to its initial value.
  • When showing elements the display property of the element to be shown is restored to its initial value. If using !important in your styles, it is necessary to override the style using .css('display', 'block !important') for the .show() method to function correctly
  • When the duration, easing or callback parameters are used, the .toggle() method becomes an animation method.
  • There is also a mouse event named .toggle() and the method that is fired depends on the set of arguments passed.

Syntax

Signature Description
.animate( properties [, duration]
                     [, easing] [, complete] )		Perform a custom animation for a set of CSS properties optionally providing a duration, and/or an easing and/or a callback function.
.animate( properties, options )Perform a custom animation for a set of CSS properties optionally providing a map of additional options.

Parameters

Parameter Description Type
propertiesA plain JavaScript object of CSS style properties that the animation will move toward.
  • All animated CSS properties should should be animated to a single numeric value which will be in pixels. The units measurements em and % can be appended to the numeric value to replace pixels where appropriate.
  • Generally non-numeric CSS properties cannot be animated using basic jQuery functionality.
  • Custom properties and some non-style properties such as scrollLeft and scrollTop can be animated.
  • Shorthand CSS properties are not fully supported so use the long versions where possible or ensure values are not set to auto.
  • You can also use the following strings 'hide', 'show' or 'toggle' instead of numerical values. These shortcuts allow for custom hiding and showing of animations, taking into account the display type of the element.
  • Animated properties can also be relative. So relative strings starting with += or -= to increment or decrement the property value, can be prepended to the numerical value.
 PlainObject
durationA string or number determining the time the animation will run for.
default: 400
  • Durations are given in milliseconds and the higher the value, the slower the animation.
  • The string 'slow' can be used which equates to 600 milliseconds.
  • The string 'fast' can be used which equates to 200 milliseconds.
String or
Number
easingSpecify the speed at which the animation progresses at different points within the animation.
default: swing
  • The string 'swing' which causes the animation to animate faster at the beginning/end and slower in the middle.
  • The string 'linear' which causes the animation to progress at a constant pace.
  • Each property can take an array as its value. The first member of the array is the string 'show', 'hide', and 'toggle' 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() methods optional easing argument. If the easing argument is not defined, the default 'swing' argument is used.
String
completeA function that fires once the animation is complete.
  • The callback is fired in the context of the current element in the set being animated, so the keyword this refers to that element.
  • The callback is fired once for each element in the matched set and can be used to string different animations together in sequence.
Function
optionsA map of additional options to pass to the method, supported keys being:

  • duration: A string or number determining the time the animation will run for.
    default: 400
    • Durations are given in milliseconds and the higher the value, the slower the animation.
    • The string 'slow' can be used which equates to 600 milliseconds.
    • The string 'fast' can be used which equates to 200 milliseconds.
  • easing: A string determining the speed at which the animation progresses at different points within the animation.
    default: swing
    • The string 'swing' which causes the animation to animate faster at the beginning/end and slower in the middle.
    • The string 'linear' which causes the animation to progress at a constant pace.
  • specialEasing: A map of one or more of the CSS properties defined by the properties argument and their corresponding easing functions.
  • step: A function to be called after each step of the animation.
    • The callback accepts two arguments:
      1. now the numeric value of the property being animated at each step
      2. fx a reference to the jQuery.fx prototype object, which contains a number of properties such as elem for the animated element, start and end for the first and last value of the animated property respectively and prop for the property being animated.
    • The callback is fired in the context of the current element in the set being animated, so the keyword this refers to that element.
    • The callback is fired once for each element in the matched set and can be used to string different animations together in sequence.
  • queue: Either a Boolean indicating whether to place the animation in the effects queue, or a string denoting the queue to add the animation to.
  • complete: A function to be called when the animation is complete.
    • The callback is fired in the context of the current element in the set being animated, so the keyword this refers to that element.
    • The callback is fired once for each element in the matched set and can be used to string different animations together in sequence.
The following options which attach a Promise object, allow us to report animation progression and notification of animation completion were added in jQuery 1.8 and are listed below:
  • progress: A function to be called after each step of the animation which will get called a maximum of one time once per animated element irrespective of the number of animated properties.
  • done: A function to be called when the animation completes.
    It's Promise object has been resolved.
  • fail: A function to be called when the animation fails to complete.
    It's Promise object has been rejected.
  • always: A function to be called when the animation ends.
    It's Promise object has been resolved or rejected.
 PlainObject

String or
Number





String






PlainObject

Function












Boolean or
String

Function








Function


Function

Function

Function

Return

A jQuery object.


.animate( properties [, duration]
                [, easing] [, complete] ) Example  Effects  <<  Top

Perform a custom animation for a set of CSS properties optionally providing a duration, and/or an easing and/or a callback function.

In the examples below we are using different properties/styles/toggles. Press the buttons to see these animations

a picture of curry a picture of curry a picture of curry


$(function(){
  $('#btn21').on('click', function() {
    $('#pie10').animate({
      opacity: 0.5,
      left: '+=20',
      height: 'toggle'
    }, 1200, 'swing' 
    );
  });
  $('#btn22').on('click', function() {
    $('#pie11').animate({
      opacity: 0.3,
      top: '+=20',
      width: 'toggle'
    }, 1200, 'linear' 
    );
  });
  $('#btn23').on('click', function() {
    $('#pie12').animate({
      opacity: 0.75,
      width: 'toggle',
      height: 'toggle',
    }, 1200, 'swing' 
    );
  });
});

Press the buttons below to action the above code:

          

.animate( properties, options ) Example  Effects  <<  Top

Perform a custom animation for a set of CSS properties optionally providing a map of additional options.

In the example below we are using toggle properties with some options.

a picture of curry a picture of curry a picture of curry a picture of curry 

$(function(){
  $('#btn24').on('click', function() {
    $('#div1 .curry11').first().animate({
        width: 'toggle',
        height: 'toggle'
    },  {
        duration: 1200,
        specialEasing: {
          width: 'linear'
        },
        complete: function() {
          // using 'callee' so we don't have to name the function
          $(this).next().toggle(400, arguments.callee);
        }
    });
  });
});

Press the buttons below to action the above code:

Related Tutorials

jQuery Intermediate Tutorials - Lesson 6 - Basic & Custom Effects