Some of the examples in this article use the $.print() function to print results to the page. This is a simple plug-in, not covered in the article.

Customized effects

We will describe how to create effects that are not provided out of the box by jQuery.

.animate()

Perform a custom animation of a set of CSS properties.

.animate(properties[, duration][, easing][, callback])
.animate(properties, options)

Parameters (first version)

• properties: A map of CSS properties that the animation will move toward
• duration (optional): A string or number determining how long the animation will run
• easing (optional): A string indicating which easing function to use for the transition
• callback (optional): A function to call once the animation is complete

Parameters (second version)

• properties: A map of CSS properties that the animation will move toward
• options: A map of additional options to pass to the method. Supported keys are:
  1. duration: A string or number determining how long the animation will run
  2. easing: A string indicating which easing function to use for the transition
  3. complete: A function to call once the animation is complete
  4. step: A function to be called after each step of the animation
  5. queue: A Boolean indicating whether to place the animation in the effects queue. If false, the animation will begin immediately
  6. specialEasing: A map of one or more of the CSS properties defined by the properties argument and their corresponding easing functions

Return value

The jQuery object, for chaining purposes.

Description

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 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 to or from the current value of the property.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The ‘fast‘ and ‘slow‘ strings can be supplied to indicate durations of 200 and 600 milliseconds, respectively. 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"
    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() {
  $.print('Animation complete.');
 });
});

Note that we have specified toggle as the target value of the height property. As 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. As 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.

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.

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 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() {
  $.print('Animation complete.');
 });
});

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() {
  $.print('Animation complete.');
  }
 });
});

As previously noted, a plug-in is required for the easeOutBounce function.