When to use jQuery animation promises instead of the callback?

Question

I have the following query. When to use this:

$('#box').hide(2000).promise().done(function(){
     $('#output').text('Box is hidden');
});

instead of this:

$('#box').hide(2000,function(){
     $('#output').text('Box is hidden');
});

What are some useful scenarios for using the .promise() method with jQuery animations?

Thank you

Answer 1

If you're just animating one item, there is little reason to use a promise over a direct callback. In this particular case, promises are more useful when you're trying to coordinate multiple different async operations (which is where promises are generally the most useful).

Suppose you had a whole bunch of items you were hiding and you wanted ONE callback when they were all done. Then, this would do exactly that:

$('.items, .boxes').hide(2000).promise().then(function(){
     $('#output').text('All hidden');
});

Or, suppose you wanted to know when multiple different animations were done so you needed to coordinate multiple actions. Promises have built-in features for that which are more work to hand-code without promises:

var p1 = $('.items, .boxes').hide(2000).promise();
var p2 = $('.sliders').slideUp(2500).promise();
var p3 = $('.openers').slideDown(1500).promise();
$.when(p1, p2, p3).then(function() {
    // all are done here
});

If you want to hand code that without promises, then you will have to maintain a counter and, in each separate callback, check the counter to see if they are all done. It's a lot more code. Now, if you there are then errors to deal with or multiple other operations chained onto this, any option without callbacks or without some async supporting library quickly becomes a real pain to hand code. That is why promises were invented.

Or, even extend beyond an animation, imagine you want to coordinate both an animation and an ajax call (which you have no idea how long it will take):

var p1 = $('.items, .boxes').hide(2000).promise();
var p2 = $.ajax(...);
$.when(p1, p2).then(function() {
    // both are done here
});

---

Here's a demo of the differences in notifications. If you press "Reset", then press "Callbacks", you will see that you get 5 completion notifications. If you press "Reset" and then press "Promises", you will see that you get 1 completion notification when they are all done.

// configure logging
log.id = "results";

$("#runPromises").click(function() {
  $('.items, .boxes').hide(2000).promise().then(function(){
       log("got done notification")
  });
});
$("#runCallbacks").click(function() {
  $('.items, .boxes').hide(2000, function(){
       log("got done notification")
  });
});

$("#reset").click(function() {
  $(".items, .boxes").show();
  $("#results").empty();
});

.items {
  height: 50px;
  width: 200px;
  background-color: red;
  margin-top: 10px;
}

.boxes {
  height: 30px;
  width: 30px;
  background-color: blue;
  margin-top: 10px;
}
#results {
  margin-top: 30px;
}

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="http://files.the-friend-family.com/log.js"></script>
<button id="runCallbacks">Callbacks</button> 
<button id="runPromises">Promises</button>
<button id="reset">Reset</button>
<div>
  <div class="items"></div>
  <div class="items"></div>
  <div class="items"></div>
  <div class="boxes"></div>
  <div class="boxes"></div>
</div>
<div id="results"></div>