.delegate()

Categories: Events > Event Handler Attachment

.delegate( selector, eventType, handler(eventObject) ) Returns: jQuery

Description: Attach a handler to one or more events for all elements that match the selector, now or in the future, based on a specific set of root elements.

version added: 1.4.2.delegate( selector, eventType, handler(eventObject) )
- selector
  
  Type: String
  
  A selector to filter the elements that trigger the event.
- eventType
  
  Type: String
  
  A string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names.
- handler(eventObject)
  
  Type: Function()
  
  A function to execute at the time the event is triggered.
version added: 1.4.2.delegate( selector, eventType, eventData, handler(eventObject) )
- selector
  
  Type: String
  
  A selector to filter the elements that trigger the event.
- eventType
  
  Type: String
  
  A string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names.
- eventData
  
  Type: Object
  
  An object containing data that will be passed to the event handler.
- handler(eventObject)
  
  Type: Function()
  
  A function to execute at the time the event is triggered.
version added: 1.4.3.delegate( selector, events )
- selector
  
  Type: String
  
  A selector to filter the elements that trigger the event.
- events
  
  Type: PlainObject
  
  A plain object of one or more event types and functions to execute for them.

As of jQuery 1.7, .delegate() has been superseded by the .on() method. For earlier versions, however, it remains the most effective means to use event delegation. More information on event binding and delegation is in the .on() method. In general, these are the equivalent templates for the two methods:

                                
                                  
                                    
                                      // jQuery 1.4.3+
                                    
                                  
                                
                                
                                  
                                    $(elements).delegate( selector, events, data, handler );
                                  
                                
                                
                                  
                                    
                                      // jQuery 1.7+
                                    
                                  
                                
                                
                                  
                                    $(elements).on( events, selector, data, handler );

For example, the following .delegate() code:

                                
                                  
                                    $("table").delegate("td", "click", function() {
                                  
                                
                                
                                  
                                      $(this).toggleClass("chosen");
                                  
                                
                                
                                  
                                    });

is equivalent to the following code written using .on():

                                
                                  
                                    $("table").on("click", "td", function() {
                                  
                                
                                
                                  
                                      $(this).toggleClass("chosen");
                                  
                                
                                
                                  
                                    });

To remove events attached with delegate(), see the .undelegate() method.

Passing and handling event data works the same way as it does for .on().

Additional Notes:

Since the .live() method handles events once they have propagated to the top of the document, it is not possible to stop propagation of live events. Similarly, events handled by .delegate() will propagate to the elements to which they are delegated; event handlers bound on any elements below it in the DOM tree will already have been executed by the time the delegated event handler is called. These handlers, therefore, may prevent the delegated handler from triggering by calling event.stopPropagation() or returning false.

Examples:

Example: Click a paragraph to add another. Note that .delegate() attaches a click event handler to all paragraphs - even new ones.

                                  
                                    
                                      
                                        <!DOCTYPE html>
                                      
                                    
                                  
                                  
                                    
                                      
                                        <html>
                                      
                                    
                                  
                                  
                                    
                                      
                                        <head>
                                      
                                    
                                  
                                  
                                    
                                        <style>
                                    
                                  
                                  
                                    
                                        p { background:yellow; font-weight:bold; cursor:pointer;
                                    
                                  
                                  
                                    
                                            padding:5px; }
                                    
                                  
                                  
                                    
                                        p.over { background: #ccc; }
                                    
                                  
                                  
                                    
                                        span { color:red; }
                                    
                                  
                                  
                                    
                                        </style>
                                    
                                  
                                  
                                    
                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    
                                  
                                  
                                    
                                      
                                        </head>
                                      
                                    
                                  
                                  
                                    
                                      
                                        <body>
                                      
                                    
                                  
                                  
                                    
                                        <p>Click me!</p>
                                    
                                  
                                  
                                    
                                       
                                    
                                  
                                  
                                    
                                        <span></span>
                                    
                                  
                                  
                                    
                                      
                                        <script>
                                        
                                      
                                    
                                  
                                  
                                    
                                          $("body").delegate("p", "click", function(){
                                    
                                  
                                  
                                    
                                            $(this).after("<p>Another paragraph!</p>");
                                    
                                  
                                  
                                    
                                          });
                                    
                                  
                                  
                                    
                                      
                                        </script>
                                      
                                    
                                  
                                  
                                    
                                       
                                    
                                  
                                  
                                    
                                      
                                        </body>
                                      
                                    
                                  
                                  
                                    
                                      
                                        </html>

Example: To display each paragraph's text in an alert box whenever it is clicked:

                                  
                                    
                                      $("body").delegate("p", "click", function(){
                                    
                                  
                                  
                                    
                                        alert( $(this).text() );
                                    
                                  
                                  
                                    
                                      });

Example: To cancel a default action and prevent it from bubbling up, return false:

1	`$("body").delegate("a", "click", function() { return false; })`

Example: To cancel only the default action by using the preventDefault method.

                                  
                                    
                                      $("body").delegate("a", "click", function(event){
                                    
                                  
                                  
                                    
                                        event.preventDefault();
                                    
                                  
                                  
                                    
                                      });

Example: Can bind custom events too.

                                  
                                    
                                      
                                        <!DOCTYPE html>
                                      
                                    
                                  
                                  
                                    
                                      
                                        <html>
                                      
                                    
                                  
                                  
                                    
                                      
                                        <head>
                                      
                                    
                                  
                                  
                                    
                                        <style>
                                    
                                  
                                  
                                    
                                        p { color:red; }
                                    
                                  
                                  
                                    
                                        span { color:blue; }
                                    
                                  
                                  
                                    
                                        </style>
                                    
                                  
                                  
                                    
                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    
                                  
                                  
                                    
                                      
                                        </head>
                                      
                                    
                                  
                                  
                                    
                                      
                                        <body>
                                      
                                    
                                  
                                  
                                    
                                        <p>Has an attached custom event.</p>
                                    
                                  
                                  
                                    
                                        <button>Trigger custom event</button>
                                    
                                  
                                  
                                    
                                        <span style="display:none;"></span>
                                    
                                  
                                  
                                    
                                      
                                        <script>
                                        
                                      
                                    
                                  
                                  
                                    
                                       
                                    
                                  
                                  
                                    
                                          $("body").delegate("p", "myCustomEvent", function(e, myName, myValue){
                                    
                                  
                                  
                                    
                                            $(this).text("Hi there!");
                                    
                                  
                                  
                                    
                                            $("span").stop().css("opacity", 1)
                                    
                                  
                                  
                                    
                                                     .text("myName = " + myName)
                                    
                                  
                                  
                                    
                                                     .fadeIn(30).fadeOut(1000);
                                    
                                  
                                  
                                    
                                          });
                                    
                                  
                                  
                                    
                                          $("button").click(function () {
                                    
                                  
                                  
                                    
                                            $("p").trigger("myCustomEvent");
                                    
                                  
                                  
                                    
                                          });
                                    
                                  
                                  
                                    
                                       
                                    
                                  
                                  
                                    
                                      
                                        </script>
                                      
                                    
                                  
                                  
                                    
                                       
                                    
                                  
                                  
                                    
                                      
                                        </body>
                                      
                                    
                                  
                                  
                                    
                                      
                                        </html>

POWERED BYHERONOTE

previous page start next page

.delegate()

jQuery