The jQuery animate() step callback function

If you’ve ever needed to do more complex animations than fades and slides, then you’ve probably encountered the jQuery animate function. The animate function allows you quite a bit more flexibility than just using fadeOut or slideDown. In fact, the oft-used fades and slides simply wrap calls to animate.

If you’ve ever looked at the jQuery animate docs at api.jquery.com you might have noticed that one of the optional arguments you can define is step which is defined as:

A function to be called after each step of the animation.

…and that’s it. If you search for “step” on the page, you won’t see another mention of it.

Fortunately, a quick search on Google for “jquery animate step” will yield the jQuery 1.2 release notes that sheds a bit of light on the step function:

You can now extend jQuery animations with a function that is fired on every step of the animation that changes the style of the element being animated. It can be extended for specific css properties, or even to create a custom animation type.

For example, you can pass in an extra step function to .animate() to perform actions like animation synchronization.

The release notes also contain a code sample:

$("#go").click(function(){
    $(".block:first").animate({ left: 100 }, {
      duration: 1000,
      step: function(now, fx){
        $(".block:gt(0)").css("left", now);
      }
    });
});

So now we know the arguments step takes: now and fx. We can also tell from the code that now contains the value being animated. fx, however, is still a bit mystery. We can solve that mystery by running the above code in Firebug, setting a break point when the step function is called, and then inspecting the fx and now objects. Here are the results of that operation:

The fx object
Attribute Type Description
elem DOM Element The element being animated.
end Number The value the animation will end at.
now Number The value the animation is currently at.
options Object Some animations options.
options.curAnim Object Information about the current animation. For example, if you passed { opacity: 0, top: "+=16" } as the first parameter of animate, then they will be attributes of this object.
options.duration Number The duration that you passed to animate.
pos Number Sweeps from 0.0 to 1.0 during the animation. Sort of like a ‘t’ value for interpolations.
prop String The CSS property being varied (e.g. “opacity” or “top”).
start Number The starting value of the CSS property being animated.
startTime Number The timestamp indicating what time the animation started.
state Number Which step of the animation we’re on. For example, if you made an animation that was moving 100px to the right over 100ms, and jQuery moves elements every 10ms, then there would be 10 states.
unit String The unit of the CSS value being animated (e.g. “px” or “em”), if applicable.

There were a couple more attributes (most of them functions) that I did not include because I either didn’t think they’d be useful or I didn’t really know what they did. If you need to know what those do, I suggest Firebugging up your code and taking a look yourself :)

7 Comments so far

  1. mav on April 20th, 2010

    Great! :)

  2. entr on June 27th, 2010

    Very useful research! Helped a lot.

  3. Szczepan Hołyszewski on July 4th, 2010

    The pos attribute sweeps from 0.0 to 1.0 during the animation. I suppose it some kind of a ‘t’ value for interpolations but I don’t know if it raw time or already mapped through the easing function.

  4. cdmckay on July 4th, 2010

    Thanks Szczepan, I’ve added that to the table.

  5. [...] best workaround is using the step callback function as suggested here. Thanks to Nick Craver for the link. Tagged: jquery, jQuery animation, jquery-selectors, [...]

  6. [...] http://cdmckay.org/blog/2010/03/01/the-jquery-animate-step-callback-function/ – Discusses the FX object properties and what they represent. [...]

  7. LewHowe on September 29th, 2013

    Amazing!Thanks!

Leave a reply

ERROR: si-captcha.php plugin says GD image support not detected in PHP!

Contact your web host and ask them why GD image support is not enabled for PHP.

ERROR: si-captcha.php plugin says imagepng function not detected in PHP!

Contact your web host and ask them why imagepng function is not enabled for PHP.