.join(queue ,usePromise ,callback)

Description: Waits until the specified animation queues of all selected elements reach their end.

queue – string, optional
the name of the queue.
Defaults to 'fx', the name of the default queue.
usePromise – boolean, optional
whether to use .promise() instead of .queue() to register the trigger.
Defaults to false.
callback – function(count…), optional
a method that is called once just before continuing the invocation chain.
All current iteration counts/events (from inner-most to outer-most loop) are passed as arguments.

Tip: .join(true) can be abbreviated by .wait().

Hint: You can also wait for a deferred object using .wait(deferred).

Attention: .promise() doesn't work correctly with non-default queues. See the current state of that jQuery bug.


Usage pattern

$('.some').join().doSome().jQueryStuff();
$('.some').join(queue).doSome().jQueryStuff();
$('.some').join(true).doSome().jQueryStuff();
$('.some').join(queue,true).doSome().jQueryStuff();

Examples with waiting for an animation queue's end

Example #16: playing pong with divs

In this example we work with two different animation queues.

The horizontal animation for the ball uses the effects queue named 'myFX'. We have to start that queue manually using .dequeue('myFX').

// the horizontal animation options
var horiz = { duration : 2000, easing : 'linear', queue : 'myFX' };

The vertical animation uses the default queue which always starts on its own. It includes all three moving elements at once.

// the vertical animation options
var vertic = { duration : 900, easing : 'linear' };

Because the two queues will be animated with different repeating intervals the ball doesn't always take the same path.

$('.example .ball').repeat()
  .animate({left:350},horiz)
  .animate({left:10},horiz).join('myFX')
  ._.dequeue('myFX');

$('.example span').repeat()
  .animate({top:160},vertic)
  .animate({top:0},vertic).join();