In many common situations, one needs to bind the same handler function to more than one event (on the same element, that is). You could always do something like this:

jQuery('div').click(function(e){
            alert('event'),
         })
         .keydown(function(e){
            alert('event'),
         });

That is not such a problem if the function is short, but for longer blocks of code, repeating them over and over won’t be that trivial and is definitely not the best approach.

There’s more than a single solution to this simple but recurrent problem.

One way to solve it without repeating yourself too much would be as follows:

function handler(e){
    alert('event'),
 }

 jQuery('div').click(handler)
         .keydown(handler);

Defining a function once and then referring to it multiple times is not a bad approach, but there’s an even simpler one provided by jQuery.

bind() accepts a list of events separated by spaces. That means you can solve the previous problem like this:

jQuery('div').bind'click keydown', function(e){
    alert('event'),
 });

You can also apply this behavior to unbind() and one().

To unbind a certain function, you need to have a reference to it, so even if you are using the multievent feature, you still need to keep a reference to the handler. If you don’t pass the function to unbind(), then any other event handler bound to that event will be removed as well:

function handler(e){
    alert('event'),
 }

 jQuery('div').bind('click keydown', handler);

 // ...

 jQuery('div').unbind('click keydown', handler);

You’ve come into a situation where you have many bindings, and the handler functions look pretty similar. It doesn’t matter whether these bindings are applied to different element/event combinations. The thing is, you don’t want to repeat yourself over and over (who does?).

Here’s an example:

jQuery('#button1').click(function(e){
     jQuery('div.panel').hide();
     jQuery('#panel1').show();
     jQuery('#desc').text('You clicked the red button'),
 });

 jQuery('#button2').click(function(e){
     jQuery('div.panel').hide();
     jQuery('#panel2').show();
     jQuery('#desc').text('You clicked the blue button'),
 });

 jQuery('#button3').click(function(e){
     jQuery('div.panel').hide();
     jQuery('#panel3').show();
     jQuery('#desc').text('You clicked the green button'),
 });

As you can see, the only differences noticed on each handler are the color and the panel to show. The amount of code would grow as you add more buttons or each time the handler functions get larger.

bind() accepts an optional data argument to be bound together with each specific handler function. The data values will be accessible from within this function by accessing event.data^[2] where event is the event object argument provided by jQuery.

Note that this value can be anything...an array, a string, a number, or an object literal.

It’s a common approach to pass an object literal, even if you are just passing one value, to make the code more readable. This way, the name you give this single attribute within the object will make your code a little more self-explanatory.

event.data is used to provide precomputed values to a function, which means the values you will be passing to bind() need to be already available at binding time. To handle more “dynamic” values, there’s another way that we’ll learn about in Recipe 8.5.

The solution to the previous problem could look something like this:

function buttonClicked(e){
     jQuery('div.panel').hide();
     jQuery('#panel'+e.data.panel).show();
     jQuery('#desc').text('You clicked the '+e.data.color+' button'),
 }

 jQuery('#button1').bind('click',{panel:1, color:'red'}, buttonClicked);
 jQuery('#button2').bind('click',{panel:2, color:'blue'}, buttonClicked);
 jQuery('#button3').bind('click',{panel:3, color:'green'}, buttonClicked);

Of course, you could make this even shorter by using a loop. This approach is called a macro by some coders, and it’s a very common approach for jQuery code.

These macros will surely reduce the code length and can sometimes improve code readability. Some other times, they’ll just make your code completely unreadable, so use them with caution.

Here’s how you could do it:

jQuery.each(['red','blue','green'], function(num, color){
     num++; // it's 0-index based
     jQuery('#button'+num).bind('click',function(e){
         jQuery('div.panel').hide();
         jQuery('#panel'+num).show();
         jQuery('#desc').text('You clicked the '+color+' button'),
     });
 })

As you can see, I haven’t used the data argument because we don’t really need it. The code is now somewhat shorter, but not that much, and it’s not more readable.

The conclusion is that both approaches can be used on this kind of situation. Depending on the problem, one could be better (shorter, more readable, easier to maintain) than the other.

So, you’ve made a plugin-like block of code that binds many event handlers to certain DOM elements.

Later, you want to clean them all up in order to dispose the plugin completely.

This could get a little lengthy if you added many handlers. Maybe you don’t even have access to the bound handlers because they belong to another local scope.

You can’t unbind every handler for a certain event (or any existing event), because you could be deleting other handlers that you didn’t take into account.

Use a unique namespace for each plugin you make. Any handler bound within this plugin must be added with this namespace.

Later, when cleaning up, you just need to “unbind the whole namespace,” and all the related event handlers will go away with one single line of code.

You need to trigger an event on a certain element (or many). This element belongs to one or more plugins so it may have event handlers bound to this event.

The problem is that this event is a common one, like click or mousedown. Simply triggering the event could run other event handlers that you didn’t expect.

On the same principle as the previous recipe, namespaces can be used for triggering as well. When binding, you need to make sure you add a unique namespace to each set of handlers.

This can also be used for the opposite situation; if you need to trigger any event except those with a namespace, you can use the ! operator. An example of this will be shown in the discussion.

You want to pass certain values to an event handler, but they’re not known at “binding time,” and they would change with each call to the handler.

There are two ways of solving this problem:

Both approaches work, and neither is clearly better than the other. The second approach was a little awkward to use before jQuery 1.3. Since this version, it has become pretty straightforward and less problematic. I’ll explain each option in detail in the “Discussion” section.

Passing data to the handler, instead of making the function grab it from somewhere (global variables, jQuery namespace, etc.), makes the code easier to maintain because you keep handler functions simple and agnostic from the environment.

This also allows you to reuse the same handler for many situations.

You need to gain access to a certain DOM element as soon as possible.

Using document.ready isn’t fast enough; you really want to control this element before the page finishes rendering.

Issues like this are especially noticeable on large pages, where the document.ready event takes longer to be reached.

This is a very common and generic problem that can be solved in many different ways.

There’s one approach that works for all of them, but it requires polling the DOM so it adds overhead to the page-rendering process (definitely undesirable!).

These are some of the usual problems where one could rely on polling:

We’ll discuss what’s the better approach for each situation in the “Discussion” section.

You have several handlers bound to the same element/event combination.

You want to, from within a handler, prevent the rest from being called, something like what event.stopPropagation()^[7] does. The problem is that event.stopPropagation() only works for elements that are below the current element in the DOM hierarchy.

Since jQuery 1.3, event objects passed to handlers have a new method called stopImmediatePropagation().^[8] This method will do just that, and no subsequent event handler will be notified of the current event. It will also stop the event’s propagation, just like stopPropagation() does.

This method has been taken from ECMAScript’s DOM level 3 events specification.^[9]

If you want to consult the event object, to know whether this method has been called, you can do so by calling event.isImmediatePropagationStopped(),^[10] which will return either true or false.

Your code is relying on the event.target^[11] property of an event object, most likely in combination with event delegation, where one single event handler is bound to a container and it manages a variable number of descendant elements.

In some cases, you don’t seem to be getting the expected behavior. event.target is sometimes pointing to an element that is inside the one you expected.

The event.target property refers to the element that got the event, that is, the specific element.

This means that if, for example, you have an image inside a link and you click the link, the event.target will be the image, not the link.

So, how should you work around this? If you’re not working with event delegation, then using this (scope of the function) or event.currentTarget (since jQuery 1.3) should do. It will always point to the element that has the event handler bound.

If you’re indeed using event delegation, then you’ll need to find the parent element you were expecting.

Since jQuery 1.3, you can use closest().^[12] As specified in its documentation, it will return the closest element, beginning with the current element and going up through the parents, that matches a certain selector.

If you’re using an older version of jQuery, you can simulate closest() with something like this:

jQuery.fn.closest = function( selector ){
    return this.map(function(){
        var $parent = jQuery(this).parents();
        return jQuery(this).add($parents).filter( selector )[0];
    });
 }

This could be improved a little for performance, but this simple version should do for general purposes.

Here’s a small example of a very common situation using closest():

jQuery('table').click(function(e){
    var $tr = jQuery(e.target).closest('tr'),
    // Do something with the table row
 });

event.target is one of the event object’s properties normalized by jQuery’s event system (event.srcElement on IE).

So, how come an event is triggered on this target element and your event handler is called even when bound to an ancestor ? The answer is Event bubbling.^[13]

Most standard DOM events do bubble.^[14] This means that, after the event was triggered on the target, it will go up to its parent node and trigger the same event (with all its handlers).

This process will continue until either it reaches the document or event.stopPropagation() is called within an event handler.

Thanks to event bubbling, you don’t need to always bind event handlers to specific elements; instead, you can bind to a common container once and handle them all from there. This is the principle of event delegation.

We all have fallen for this at least once. You set up something like this:

jQuery('#something').hover(
    function(){
        // add some cool animation for jQuery(this)
    },
    function(){
        // Revert the cool animation to its initial state
    }
);

For example, you could be enlarging an element each time the mouse rolls over it and then shrinking it to its initial size once the mouse rolls out.

All goes well until you quickly move the mouse over and out of the element and...what?!

The jQuery('#something') element suddenly gets resized back and forth many times until it finally stops.

The solution is indeed simple, too simple, but the problem is so recurrent that I really consider this solution a useful one.

What you need to do in order to avoid this nasty effect is simply kill all existing animations on the element before you create a new one.

To do so, you have to use jQuery’s stop() method. It will (as the name says) stop the current animation and, optionally, remove the following ones as well.

You’ve bound one or more event handlers, and they suddenly stop working.

It happens after new elements are added dynamically by an Ajax request or simple jQuery operations (append(), wrap(), etc.).

There are two possible solutions for this recurring problem, each with its own pros and cons: