.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"
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"
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, then the message gets printed. 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. - 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.
Caveats
The .live() technique is useful, but due to its special approach cannot be simply substituted for .bind() in all cases. Specific differences include:
.live() method supports custom events as well as all JavaScript events. As of jQuery 1.4.1 even focus and blur work with live (mapping to the more appropriate, bubbling, events focusin and focusout). Additionally, as of jQuery 1.4.1 the hover event can be specified (mapping to "mouseenter mouseleave"). In version 1.3.x, however, 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..live(). Rather, the .live() method should always be called directly after a selector, as in the example above..live(), the handler must return false. Calling .stopPropagation() will not accomplish this.See the discussion for .bind() for more information on event binding.
As of jQuery 1.4.1 you can also pass in multiple events to live, similarly to the functionality provided in .bind().
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.
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.