Skip to main content
Ben Nadel at dev.Objective() 2015 (Bloomington, MN) with: Kev McCabe
Ben Nadel at dev.Objective() 2015 (Bloomington, MN) with: Kev McCabe

jQuery Can Provide Queue-Based Promise Objects

By
Published in Comments (3)

Last week, I was looking up some Promise information in the jQuery API when I came across the .promise() fn-method. While I have worked with promises in the context of AJAX and explicit Deferred objects, it seems that jQuery provides implicit promise functionality around their queues and dequeuing functionality. This allows for promise objects to be returned for animations, which are, after all, nothing more than encapsulated "fx" queues.

By default, the animation methods in jQuery (animate(), slideDown(), slideUp(), etc.) return a reference to the jQuery object (in order to maintain method chaining). And traditionally, if you want to perform an action after an animation is complete, you have to provide some sort of callback as an argument or property of the animation configuration.

With the .promise() method, however, you can get a promise object that will be resolved once the animation is done. This provides for more readable code (in my opinion) with the option for multiple callback handlers. To see what I'm talking about, take a look at the following code. In this demo, we're going to hide and show a DIV and alter the "action text" once the animation has been completed.

<!DOCTYPE html>
<html>
<head>
	<title>jQuery Can Provide Queue-Based Promise Objects</title>

	<style type="text/css">

		div.container > div.buffer {
			background-color: #E0E0E0 ;
			border: 1px solid #CCCCCC ;
			height: 200px ;
			padding: 10px 10px 10px 10px ;
			}

	</style>
</head>
<body>

	<h1>
		jQuery Can Provide Queue-Based Promise Objects
	</h1>

	<p>
		<a href="#" class="action">
			<span class="intent">Hide</span> Div
		</a>
	</p>

	<div class="container">
		<div class="buffer">

			Hello, I am a div! How you like me now?

		</div>
	</div>


	<!-- Include scripts. -->
	<script type="text/javascript" src="./jquery-1.6.4.js"></script>
	<script type="text/javascript">


		// Get a reference to some DOM elements.
		var action = $( "a.action" );
		var actionIntent = action.find( "span.intent" );
		var container = $( "div.container" );

		// Hook up the click action.
		action.click(
			function( event ){

				// Prevent the real event - not a true link.
				event.preventDefault();

				// Check to make sure we're not currently animating
				// the DIV.
				if (container.is( ":animated" )){

					// Let the animation continue before the action
					// link becomes a viable action.
					return;

				}

				// Toggle the container. When implementing this
				// animation, get a PROMISE object for the animating
				// DOM element so that we can attach completion
				// handlers to it.
				var promise = container.slideToggle().promise();

				// When the animation is done, update the text within
				// the action link.
				promise.done(
					function(){

						// Set the text of the action intent.
						if (container.is( ":visible" )){

							actionIntent.text( "Hide" );

						} else {

							actionIntent.text( "Show" );

						}

					}
				);

			}
		);


	</script>

</body>
</html>

As you can see, we are using the .slideToggle() method for animation. However, after we call the slideToggle() method, we are chaining it with the promise() method:

var promise = container.slideToggle().promise();

This returns a promise object rather than the jQuery object. Once we have the promise object, we can start to attach completion handlers using the done() method. This allows us to invoke zero or more callbacks once the animation has completed.

The documentation for the .promise() method doesn't mention anything about fail() outcomes. In my testing, I found that calling stop() on an animation did not trigger a fail() callback handler. However, if I called stop() and included the jump-to-end parameter, the done() callbacks would be invoked. So, it looks as if the only viable callback collection will be that of a successful completion.

Using .promise() with jQuery animation is not revolutionary. It doesn't provide any completely new functionality. What it does provide is a way to define callbacks in an easier, more readable, more flexible way. Also, when you consider the $.when() method, queue-based promise objects make it much easier to coordinate multiple animations.

Want to use code from this post? Check out the license.

Reader Comments

3 Comments

This is cool because other methods to deal with the timing would involve timeouts, but due to congestion in the single-threaded JS execution order events could trigger out of synch and this removes that problem. Cool!

15,880 Comments

@Randy,

I think the animation queue still works with timeouts under the hood; but the nice thing about this is that it will work with custom made queues as well.

I believe in love. I believe in compassion. I believe in human rights. I believe that we can afford to give more of these gifts to the world around us because it costs us nothing to be decent and kind and understanding. And, I want you to know that when you land on this site, you are accepted for who you are, no matter how you identify, what truths you live, or whatever kind of goofy shit makes you feel alive! Rock on with your bad self!
Ben Nadel