jQuery Pocket Reference

Chapter 4. Events

One of the difficulties of working with events in client-side JavaScript is that IE (until IE9) implements a different event API than all other browsers. To address this difficulty, jQuery defines a uniform event API that works in all browsers. In its simple form, the jQuery API is easier to use than the standard or IE event APIs. And in its more complex full-featured form, the jQuery API is more powerful than the standard API. The sections below have all the details.

Simple Event Handler Registration

jQuery defines simple event registration methods for each of the commonly used and universally implemented browser events. To register an event handler for “click” events, for example, just call the click() method:

// Clicking on any <p> gives it a gray background
$("p").click(function() {
    $(this).css("background-color", "gray");
});

Calling a jQuery event registration method registers your handler on all of the selected elements. This is typically much easier than one-at-a-time event handler registration with addEventListener() or attachEvent().

These are the simple event handler registration methods jQuery defines:

blur()       focusin()       mousedown()     mouseup()
change()     focusout()      mouseenter()    resize()
click()      keydown()       mouseleave()    scroll()
dblclick()   keypress()      mousemove()     select()
error()      keyup()         mouseout()      submit()
focus()      load()          mouseover()     unload()

Most of these registration methods are for common event types with which you are probably already familiar. A few notes are in order, however. “focus” and “blur” events do not bubble, but the “focusin” and “focusout” events do, and jQuery ensures that these events work in all browsers. Conversely, the “mouseover” and “mouseout” events do bubble, which is often inconvenient because it is difficult to know whether the mouse has left the element you’re interested in, or whether it has simply moved out of one of the descendants of that element. “mouseenter” and “mouseleave” are nonbubbling events that solve this problem. These event types were originally introduced by IE, and jQuery ensures that they work correctly in all browsers.

The “resize” and “unload” event types are only ever fired on the Window object, so if you want to register handlers for these event types, you should invoke the resize() and unload() methods on $(window). The scroll() method is also most often used on $(window), but it can also be used on any element that has scrollbars (such as when the CSS overflow attribute is set to “scroll” or “auto”). The load() method can be called on $(window) to register a “load” handler for the window, but it is usually better to pass your initialization function directly to $(), as shown in The jQuery() Function. You can use the load() method on iframes and images, however. Note that when invoked with different arguments, load() is also used to load new content (via scripted HTTP) into an element—see The load() Method. The error() method can be used on <img> elements to register handlers that are invoked if an image fails to load. It should not be used to set the Window onerror property.

In addition to these simple event registration methods, there are two special forms that are sometimes useful. The hover() method registers handlers for “mouseenter” and “mouseleave” events. Calling hover(f,g) is like calling mouseenter(f) and then calling mouseleave(g). If you pass just one argument to hover(), that function is used as the handler for both enter and leave events.

The other special event registration method is toggle(). This method binds event handler functions to the “click” event. You specify two or more handler functions and jQuery invokes one of them each time a click event occurs. If you call toggle(f,g,h), for example, the function f() is invoked to handle the first click event, g() is invoked to handle the second, h() is invoked to handle the third, and f() is invoked again to handle the fourth click event. Be careful when using toggle(): as we’ll see in Simple Effects, this method can also be used to show or hide (i.e., toggle the visibility of) the selected elements.

We’ll learn about other more general ways to register event handlers in the section Advanced Event Handler Registration, and we’ll end this section with one more simple and convenient way to register handlers. Recall that you can pass a string of HTML to $() to create the elements described by that string, and that you can pass (as a second argument) an object of attributes to be set on the newly created elements. This second argument can be any object that you would pass to the attr() method. But, if any of the properties have the same name as the event registration methods listed above, the property value is taken as a handler function and is registered as a handler for the named event type. For example:

$("<img/>", {
    src: image_url,
    alt: image_description,
    className: "translucent_image",
    click: function() { $(this).css("opacity", "50%"); }
});