The queue method

The queue method allows us to work with a queue of functions bound to an element. See also the clearQueue method, which allows us to remove all functions from the queue that have not been run.

Syntax

This is how we display the queue of functions being executed, bound to the element. You can optionally pass the queue name as a string (by default fx is the standard effects queue):

.queue([queue name]);

We can manipulate the queue. This is done once for each element. To do this, you can pass an array of functions as the second parameter that will replace the contents of the current queue:

.queue([queue name], new queue );

Or you can pass a new callback function to add to the queue as the second parameter. This function in turn receives another function as a parameter. This allows you to automatically remove the next element from the queue and move the queue:

.queue([queue name], callback-function(next) {
	next();
});

Each element can have one or more queues. Many applications use only one (fx). Queues allow a sequence of actions on an element to be performed asynchronously, without interrupting program execution. Calling queue with a callback function allows us to push a new function to the end of the queue. The callback function is executed once for each element in the set. When adding a function with queue, we must ensure that dequeue is called afterwards, so that the next function in the chain will work.

Example

Let's add a custom function. First, after pressing #animate, we show a red square that moves to the right for 2s, then using queue we add a custom function that will recolor the square to green, adding the newcolor class. As you can see, dequeue is then called here to remove the function from the queue. Then our square will move to the left for half a second and recolor back to red - using the second custom function we remove the newcolor class. When the animation is finished, we collapse our square:

<button id="animate">start</button>
<div></div>

div {
	position: absolute;
	margin: 3px;
	width: 50px;
	height: 50px;
	left: 0px;
	top: 30px;
	background: red;
	display: none;
}

div.newcolor {
	background: green;
}

$('#animate').click(function() {
	$('div')
		.show('slow')
		.animate({left: '+=200'}, 2000)
		.queue(function() {
			$(this).addClass('newcolor').dequeue();
		})
		.animate({left: '-=200'}, 500)
		.queue(function() {
			$(this).removeClass('newcolor').dequeue();
		})
		.slideUp();
});

Example

Let's add a queue as an array to remove the previous one. When we click on the #start button, we will see the animation from the previous example. When we click on the #stop button, we will stop the animation by adding an empty array. When we click on #start again, the animation will start over:

<button id="start">start</button>
<button id="stop">stop</button>
<div></div>

div {
	position: absolute;
	margin: 3px;
	width: 50px;
	height: 50px;
	left: 0px;
	top: 30px;
	background: red;
	display: none;
}
div.newcolor {
	background: green;
}

$('#start').click(function() {
	$('div')
		.show('slow')
		.animate({left: '+=200'}, 5000)
		.queue(function() {
			$(this).addClass('newcolor').dequeue();
		})
		.animate({left: '-=200'}, 1500)
		.queue(function() {
			$(this).removeClass('newcolor').dequeue();
		})
		.slideUp();
});
	
$('#stop').click(function() {
	$('div').queue('fx', []).stop();
});