deferred jQuery chains and animations
Joining animations and the timed invocation chain

Timed Invocation Chain vs. Effects Queue

jQuery has a built-in mechanism for scheduling animations and effects. This is meant with effects queue (in short: fxq). This mechanism supports a wide range of animations, delays, custom queuing and unqueuing, etc. Nevertheless there are several differences between the queue and the chain. The following table tries to give a first idea:

Combining animation queues and deferred jQuery chains

As you can see in the table above the concepts are quite different. Let's say it this way: the animation queue is one way to schedule effects and the deferred jQuery chain is another way to time anything.

Actually combining both concepts enables us to create complex behaviour with very few lines of code. Follow the links in the right box to the API entries of jquery-timing synchronizing deferred chains and animation queues.

.wait(…), .join(…), and .animate(…,$) – the differences

$('.some').animate({left:100}); $('.some').wait().jQueryStuff();
//
$('.some').animate({left:100}); $('.some').join().jQueryStuff();
//
$('.some').animate({left:100},$).jQueryStuff();

Let's find out their differences:

.wait()

The easiest way to wait for animations' end calls .wait(). Internally it uses jQuery's .promise() method. Hence it only works with jQuery 1.6 and later. For earlier versions of jQuery this method will just don't wait.

We can create a case where .promise() never resolves. So this also leads to .wait() never continuing our jQuery chain:

// assure that the effects queue never gets empty
$('#example').repeat().fadeOut('slow').fadeIn('slow').join();

// do some action after .wait() - it will never happen:
$('#example').text(".wait() didn't fire").wait().text('.wait() fired!!');

.join(type)

Another method, .join(), allows to define in detail, which effects queue to wait for or whether to use .queue()/.promise() internally. If you skip the parameter usePromise or set it to false, then the .queue(function(next){…}) mechanism is used internally to register the continuation of the jQuery chain. It works with jQuery 1.4 and later.

The never continuing case above would change when using .join(). This actually would continue after one fadeOut/fadeIn iteration. But jQuery's queue mechanism can be interrupted by .stop(). So this also applies to .join(). Let's look at another case, where .join() will never fire:

// start some animations and interrupt them after 10ms
$('#example').fadeOut('slow').wait(10).stop(true);

// do some action after .join() - it will never happen:
$('#example').text(".join() didn't fire").join().text('.join() fired!!');

.join(type, true)

Setting usePromise to true will enforce the internal usage of .promise().done(function(){…}) for callback registration. As there is no .promise() prior to jQuery 1.6 this won't work with earlier versions.

Compared to the previously listed methods this variant behaves like the .wait() case. But it additionally allows to specify any named animation queue to wait for.

.animate(…,$)

There is also a direct way to wait for animations. Within any animation method that supports callback methods (e.g. animate(), fadeIn(), fadeOut(), slideUp(), slideDown(), …) you can replace the callback parameter by the jQuery token, $. This automatically turns the method call into a timed method call starting a deferred jQuery chain. The invocation chain continues when the animation triggers its callback.

Again we can create a case where this way of synchronization doesn't continue. Here we use that animations which are interrupted by .stop(true) will not trigger their callback:

// interrupt all animations after 10ms
$('#example').wait(10).stop(true);

// do some action after .fadeOut($) - it will never happen:
$('#example').text(".fadeOut($) waiting").fadeOut($).text('fired!!');

It's up to you, the developer, to choose the best fitting synchronization method for your use case. Take a look at our example section to see these methods in action.