.promise()

jQuery

previous page next page

.promise()

Categories: Deferred Object

.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: String
      The type of queue that needs to be observed.
    • target
      Type: PlainObject
      Object 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:

Example: Using .promise() on a collection with no active animation returns a resolved Promise:

1
2
3
4
5
6
 
                                  

                                    

                                      var div = $( "<div />" );
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      div.promise().done(function( arg1 ) {
                                    

                                  

                                  

                                    

                                        // will fire right away and alert "true"
                                    

                                  

                                  

                                    

                                        alert( this === div && arg1 === div );
                                    

                                  

                                  

                                    

                                      });

Example: Resolve the returned Promise when all animations have ended (including those initiated in the animation callback or added later on):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>
                                    

                                  

                                  

                                    

                                      div {
                                    

                                  

                                  

                                    

                                        height: 50px; width: 50px;
                                    

                                  

                                  

                                    

                                        float: left; margin-right: 10px;
                                    

                                  

                                  

                                    

                                        display: none; background-color: #090;
                                    

                                  

                                  

                                    

                                      
                                        }
                                      
                                    

                                  

                                  

                                    

                                      
                                        </style>
                                      
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.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>

Example: Resolve the returned Promise using a $.when() statement (the .promise() method makes it possible to do this with jQuery collections):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>
                                    

                                  

                                  

                                    

                                      div {
                                    

                                  

                                  

                                    

                                        height: 50px; width: 50px;
                                    

                                  

                                  

                                    

                                        float: left; margin-right: 10px;
                                    

                                  

                                  

                                    

                                        display: none; background-color: #090;
                                    

                                  

                                  

                                    

                                      
                                        }
                                      
                                    

                                  

                                  

                                    

                                      
                                        </style>
                                      
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.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>
 POWERED BYHERONOTE
previous page start next page