.live()
.live( eventType, handler ) Returns: jQuery
Description: Attach a handler to the event for all elements which match the current selector, now or in the future.
-
version added: 1.3.live( eventType, handler )
eventTypeA 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.
handlerA function to execute at the time the event is triggered.
-
version added: 1.4.live( eventType, eventData, handler )
eventTypeA 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.
eventDataA map of data that will be passed to the event handler.
handlerA function to execute at the time the event is triggered.
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:
<body>
<div class="clickme">
Click here
</div>
</body>
We can 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('<div class="clickme">Another target</div>');
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. If we 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('<div class="clickme">Another target</div>');
Then clicks on the new element will also trigger the handler.
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 our example, when the new element is clicked, the following steps occur:
- A click event is generated and passed to the
<div>for handling. - No handler is directly bound to the
<div>, 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
clickhandler bound by.live()executes. - This handler tests the
targetof 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, we 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
}
});
Event Data
As of jQuery 1.4, the optional eventData parameter allows us to pass 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, we 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 <div class="clickme"> 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 fully 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 returnfalse. Calling.stopPropagation()will not accomplish this. - 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, andmouseup.
- As of jQuery 1.4 the
.live()method supports custom events as well as all JavaScript events. As of jQuery 1.4.1 evenfocusandblurwork with live (mapping to the more appropriate, bubbling, eventsfocusinandfocusout).- As of jQuery 1.4.1 the
hoverevent can be specified (mapping to "mouseenter mouseleave").
Examples:
Example: Click a paragraph to add another. Note that .live() binds the click event 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>
$("p").live("click", function(){
$(this).after("<p>Another paragraph!</p>");
});
</script>
</body>
</html>Demo:
Example: To display each paragraph's text in an alert box whenever it is clicked:
$("p").live("click", function(){
alert( $(this).text() );
});Example: To cancel a default action and prevent it from bubbling up, return false:
$("a").live("click", function() { return false; })Example: To cancel only the default action by using the preventDefault method.
$("a").live("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>
$("p").live("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>
Support requests, bug reports, and off-topic comments will be deleted without warning.