.promise( [type ] [, target ] )Returns: Promise
Description: Return a Promise object to observe when all actions of a certain type bound to the collection, queued or not, have finished.
-
version added: 1.6.promise( [type ] [, target ] )
- type (default:
fx)Type: StringThe type of queue that needs to be observed. - targetType: PlainObjectObject onto which the promise methods have to be attached
-
The .promise() method returns a dynamically generated Promise that is resolved once all actions of a certain type bound to the collection, queued or not, have ended.
By default, type is "fx", which means the returned Promise is resolved when all animations of the selected elements have completed.
Resolve context and sole argument is the collection onto which .promise() has been called.
If target is provided, .promise() will attach the methods onto it and then return this object rather than create a new one. This can be useful to attach the Promise behavior to an object that already exists.
Note: The returned Promise is linked to a Deferred object stored on the .data() for an element. Since the.remove() method removes the element's data as well as the element itself, it will prevent any of the element's unresolved Promises from resolving. If it is necessary to remove an element from the DOM before its Promise is resolved, use .detach() instead and follow with .removeData() after resolution.
Examples:
Using .promise() on a collection with no active animation returns a resolved Promise:
var div = $( "<div>" );
div.promise().done(function( arg1 ) {
// Will fire right away and alert "true"
alert( this === div && arg1 === div );
}); Resolve the returned Promise when all animations have ended (including those initiated in the animation callback or added later on):
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>promise demo</title>
<style>
div {
height: 50px;
width: 50px;
float: left;
margin-right: 10px;
display: none;
background-color: #090;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button>Go</button>
<p>Ready...</p>
<div></div>
<div></div>
<div></div>
<div></div>
<script>
$( "button" ).on( "click", function() {
$( "p" ).append( "Started..." );
$( "div" ).each(function( i ) {
$( this ).fadeIn().fadeOut( 1000 * ( i + 1 ) );
});
$( "div" ).promise().done(function() {
$( "p" ).append( " Finished! " );
});
});
</script>
</body>
</html> Demo:
Resolve the returned Promise using a $.when() statement (the .promise() method makes it possible to do this with jQuery collections):
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>promise demo</title>
<style>
div {
height: 50px;
width: 50px;
float: left;
margin-right: 10px;
display: none;
background-color: #090;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button>Go</button>
<p>Ready...</p>
<div></div>
<div></div>
<div></div>
<div></div>
<script>
var effect = function() {
return $( "div" ).fadeIn( 800 ).delay( 1200 ).fadeOut();
};
$( "button" ).on( "click", function() {
$( "p" ).append( " Started... " );
$.when( effect() ).done(function() {
$( "p" ).append( " Finished! " );
});
});
</script>
</body>
</html>