Returns: jQuery
.live(eventType, handler)
eventType A string containing a JavaScript event type, such as "click" or "keydown." As of jQuery 1.4 the string can contain multiple, space-separated event types or custom event names, as well.
handler A function to execute at the time the event is triggered.
.live(eventType, eventData, handler)
eventType A string containing a JavaScript event type, such as "click" or "keydown." As of jQuery 1.4 the string can contain multiple, space-separated event types or custom event names, as well.
eventData A map of data that will be passed to the event handler.
handler A function to execute at the time the event is triggered.
.live(events)
events A map of one or more JavaScript event types and functions to execute for them.
Attach a handler to the event for all elements which match the current selector, now and in the future.
This method is a variation on the basic .bind() method for attaching event handlers to elements. When .bind() is called, the elements that the jQuery object refers to get the handler attached; elements that get introduced later do not, so they would require another .bind() call. For instance, consider the HTML:
Click here
To bind a simple click handler to this element:
$('.clickme').bind('click', function() {
// Bound handler called.
});
When the element is clicked, the handler is called. However, suppose that after this, another element is added:
$('body').append('
Another target
');
This new element also matches the selector .clickme, but since it was added after the call to .bind(), clicks on it will do nothing.
The .live() method provides an alternative to this behavior. To bind a click handler to the target element using this method:
$('.clickme').live('click', function() {
// Live handler called.
});
And then later add a new element:
$('body').append('
Another target
');
Then clicks on the new element will also trigger the handler.
To unbind the click handlers from all
that were bound using .live(), use the .die() method:
$(".clickme").die("click");
Event Delegation
The .live() method is able to affect elements that have not yet been added to the DOM through the use of event delegation: a handler bound to an ancestor element is responsible for events that are triggered on its descendants. The handler passed to .live() is never bound to an element; instead, .live() binds a special handler to the root of the DOM tree. In the example above, when the new element is clicked, the following steps occur:
A click event is generated and passed to the
for handling.
No handler is directly bound to the
, so the event bubbles up the DOM tree.
The event bubbles up until it reaches the root of the tree, which is where .live() binds its special handlers by default.
* As of jQuery 1.4, event bubbling can optionally stop at a DOM element "context".
The special click handler bound by .live() executes.
This handler tests the target of the event object to see whether it should continue. This test is performed by checking if $(event.target).closest(".clickme") is able to locate a matching element.
If a matching element is found, the original handler is called on it.
Because the test in step 5 is not performed until the event occurs, elements can be added at any time and still respond to events.
See the discussion for .bind() for more information on event binding.
Multiple Events
As of jQuery 1.4.1 .live() can accept multiple, space-separated events, similar to the functionality provided in .bind(). For example, you can "live bind" the mouseover and mouseout events at the same time like so:
$(".hoverme").live("mouseover mouseout", function(event) {
if ( event.type == "mouseover" ) {
// do something on mouseover
} else {
// do something on mouseout
}
});
As of jQuery 1.4.3, you can bind multiple live event handlers simultaneously by passing a map of event type/handler pairs:
$("a").live({
click: function() {
// do something on click
},
mouseover: function() {
// do something on mouseover
}
});
Event Data
As of jQuery 1.4, the optional eventData parameter is available for passing additional information to the handler. One handy use of this parameter is to work around issues caused by closures. See the .bind() method's "Passing Event Data" discussion for more information.
Event Context
As of jQuery 1.4, live events can be bound to a DOM element "context" rather than to the default document root. To set this context, use the jQuery() function's second argument, passing in a single DOM element (as opposed to a jQuery collection or a selector).
$("div.clickme", $("#container")[0]).live("click", function() {
// Live handler called.
});
The live handler in this example is called only when
is a descendant of an element with an ID of "container."
Caveats
The .live() technique is useful, but due to its special approach cannot be simply substituted for .bind() in all cases. Specific differences include:
DOM traversal methods are not supported for finding elements to send to .live(). Rather, the .live() method should always be called directly after a selector, as in the example above.
To stop further handlers from executing after one bound using .live(), the handler must return false. Calling .stopPropagation() will not accomplish this.
The paste and reset events, in addition to change when used with inputs of type "file," are not fully supported by the .live() method, due to issues with simulating event bubbling in Internet Explorer. In these cases, the .bind() method can be used instead.
In jQuery 1.3.x only the following JavaScript events (in addition to custom events) could be bound with .live(): click, dblclick, keydown, keypress, keyup, mousedown, mousemove, mouseout, mouseover, and mouseup.
As of jQuery 1.4 the .live() method supports custom events as well as all JavaScript events that bubble.
As of jQuery 1.4.1 even focus and blur work with live (mapping to the more appropriate, bubbling, events focusin and focusout).
As of jQuery 1.4.1 the hover event can be specified (mapping to mouseenter and mouseleave, which, in turn, are mapped to mouseover and mouseout).
Example Demo < 1 >
Click a paragraph to add another. Note that .live() binds the click event to all paragraphs - even new ones.
Click me!
Comments