.animate(…, $)

Description: Push an animation onto the animation queue and postpone ongoing invocation until the animation finished.

… – miscellaneous parameters
any animation parameter accepted by the original .animate().
$ – the jQuery token
use $ instead of "complete" function for .animate().

Tip: Many other methods that internally call .animate() and pass the callback function will automatically support that timing, too:
.fadeIn(…,$), .fadeOut(…,$), .fadeToggle(…,$), .slideUp(…,$), .slideDown(…,$), .slideToggle(…,$), etc…

Usage pattern


Examples with timed version of .animate()

Example #17: scheduling different elements' animations

Here we use an instant repeat-loop together with a sequential each-loop.

In each iteration step we wait until the element is completely shifted up using .animate({opacity:0,top:-50},$)​. Then the next animation is queued with .animate({opacity:1,top:0}), which shifts the element down again but without waiting. The loop starts its next iteration, now using the next element. So we have one element going up and another element going down simultaneously.

As you see the usage of $ as token in place of the animate callback handler decides about whether to wait for the animation to finish.

$('.example span').repeat().each($)

Example #19: pause animation cycle on mouseover

There is a animation cycle rotating three images. Once you move the mouse cursor over it, it pauses until the mouse is moved away.

A little helper function checks whether the mouse is over the image. If that's the case a deferred jQuery object waiting for the mouseleave event is returned.
function noHover() {
    return this.is(':hover') ? this.wait('mouseleave') : this

The running loop can be written in a single jQuery line.

$('#images > img').hide().repeat().each($).fadeIn($)