.bind()
.bind( eventType [, eventData] , handler(eventObject) ) Returns: jQuery
Description: Attach a handler to an event for the elements.
-
version added: 1.0.bind( eventType [, eventData], handler(eventObject) )
eventTypeA string containing one or more DOM event types, such as "click" or "submit," or custom event names.
eventDataA map of data that will be passed to the event handler.
handler(eventObject)A function to execute each time the event is triggered.
-
version added: 1.4.3.bind( eventType [, eventData], preventBubble )
eventTypeA string containing one or more DOM event types, such as "click" or "submit," or custom event names.
eventDataA map of data that will be passed to the event handler.
preventBubbleSetting the third argument to false will attach a function that prevents the default action from occurring and stops the event from bubbling. The default is true.
-
version added: 1.4.bind( events )
eventsA map of one or more DOM event types and functions to execute for them.
As of jQuery 1.7, the .on() method is the preferred method for attaching event handlers to a document. For earlier versions, the .bind() method is used for attaching an event handler directly to elements. Handlers are attached to the currently selected elements in the jQuery object, so those elements must exist at the point the call to .bind() occurs. For more flexible event binding, see the discussion of event delegation in .on() or .delegate().
Any string is legal for eventType; if the string is not the name of a native DOM event, then the handler is bound to a custom event. These events are never called by the browser, but may be triggered manually from other JavaScript code using .trigger() or .triggerHandler().
If the eventType string contains a period (.) character, then the event is namespaced. The period character separates the event from its namespace. For example, in the call .bind('click.name', handler), the string click is the event type, and the string name is the namespace. Namespacing allows us to unbind or trigger some events of a type without affecting others. See the discussion of .unbind() for more information.
There are shorthand methods for some standard browser events such as .click() that can be used to attach or trigger event handlers. For a complete list of shorthand methods, see the events category.
When an event reaches an element, all handlers bound to that event type for the element are fired. If there are multiple handlers registered, they will always execute in the order in which they were bound. After all handlers have executed, the event continues along the normal event propagation path.
A basic usage of .bind() is:
$('#foo').bind('click', function() {
alert('User clicked on "foo."');
});
This code will cause the element with an ID of foo to respond to the click event. When a user clicks inside this element thereafter, the alert will be shown.
Multiple Events
Multiple event types can be bound at once by including each one separated by a space:
$('#foo').bind('mouseenter mouseleave', function() {
$(this).toggleClass('entered');
});
The effect of this on <div id="foo"> (when it does not initially have the "entered" class) is to add the "entered" class when the mouse enters the <div> and remove the class when the mouse leaves.
As of jQuery 1.4 we can bind multiple event handlers simultaneously by passing a map of event type/handler pairs:
$('#foo').bind({
click: function() {
// do something on click
},
mouseenter: function() {
// do something on mouseenter
}
});
Event Handlers
The handler parameter takes a callback function, as shown above. Within the handler, the keyword this refers to the DOM element to which the handler is bound. To make use of the element in jQuery, it can be passed to the normal $() function. For example:
$('#foo').bind('click', function() {
alert($(this).text());
});
After this code is executed, when the user clicks inside the element with an ID of foo, its text contents will be shown as an alert.
As of jQuery 1.4.2 duplicate event handlers can be bound to an element instead of being discarded. This is useful when the event data feature is being used, or when other unique data resides in a closure around the event handler function.
In jQuery 1.4.3 you can now pass in false in place of an event handler. This will bind an event handler equivalent to: function(){ return false; }. This function can be removed at a later time by calling: .unbind( eventName, false ).
The Event object
The handler callback function can also take parameters. When the function is called, the event object will be passed to the first parameter.
The event object is often unnecessary and the parameter omitted, as sufficient context is usually available when the handler is bound to know exactly what needs to be done when the handler is triggered. However, at times it becomes necessary to gather more information about the user's environment at the time the event was initiated. View the full Event Object.
Returning false from a handler is equivalent to calling both .preventDefault() and .stopPropagation() on the event object.
Using the event object in a handler looks like this:
$(document).ready(function() {
$('#foo').bind('click', function(event) {
alert('The mouse cursor is at ('
+ event.pageX + ', ' + event.pageY + ')');
});
});
Note the parameter added to the anonymous function. This code will cause a click on the element with ID foo to report the page coordinates of the mouse cursor at the time of the click.
Passing Event Data
The optional eventData parameter is not commonly used. When provided, this argument allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. For example, suppose we have two event handlers that both refer to the same external variable:
var message = 'Spoon!';
$('#foo').bind('click', function() {
alert(message);
});
message = 'Not in the face!';
$('#bar').bind('click', function() {
alert(message);
});
Because the handlers are closures that both have message in their environment, both will display the message Not in the face! when triggered. The variable's value has changed. To sidestep this, we can pass the message in using eventData:
var message = 'Spoon!';
$('#foo').bind('click', {msg: message}, function(event) {
alert(event.data.msg);
});
message = 'Not in the face!';
$('#bar').bind('click', {msg: message}, function(event) {
alert(event.data.msg);
});
This time the variable is not referred to directly within the handlers; instead, the variable is passed in by value through eventData, which fixes the value at the time the event is bound. The first handler will now display Spoon! while the second will alert Not in the face!
Note that objects are passed to functions by reference, which further complicates this scenario.
If eventData is present, it is the second argument to the .bind() method; if no additional data needs to be sent to the handler, then the callback is passed as the second and final argument.
See the
.trigger()method reference for a way to pass data to a handler at the time the event happens rather than when the handler is bound.
As of jQuery 1.4 we can no longer attach data (and thus, events) to object, embed, or applet elements because critical errors occur when attaching data to Java applets.
Note: Although demonstrated in the next example, it is inadvisable to bind handlers to both the click and dblclick events for the same element. The sequence of events triggered varies from browser to browser, with some receiving two click events before the dblclick and others only one. Double-click sensitivity (maximum time between clicks that is detected as a double click) can vary by operating system and browser, and is often user-configurable.
Examples:
Example: Handle click and double-click for the paragraph. Note: the coordinates are window relative, so in this case relative to the demo iframe.
<!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 or double click here.</p>
<span></span>
<script>
$("p").bind("click", function(event){
var str = "( " + event.pageX + ", " + event.pageY + " )";
$("span").text("Click happened! " + str);
});
$("p").bind("dblclick", function(){
$("span").text("Double-click happened in " + this.nodeName);
});
$("p").bind("mouseenter mouseleave", function(event){
$(this).toggleClass("over");
});
</script>
</body>
</html>Demo:
Example: To display each paragraph's text in an alert box whenever it is clicked:
$("p").bind("click", function(){
alert( $(this).text() );
});Example: You can pass some extra data before the event handler:
function handler(event) {
alert(event.data.foo);
}
$("p").bind("click", {foo: "bar"}, handler)Example: Cancel a default action and prevent it from bubbling up by returning false:
$("form").bind("submit", function() { return false; })Example: Cancel only the default action by using the .preventDefault() method.
$("form").bind("submit", function(event) {
event.preventDefault();
});Example: Stop an event from bubbling without preventing the default action by using the .stopPropagation() method.
$("form").bind("submit", function(event) {
event.stopPropagation();
});Example: Bind custom events.
<!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").bind("myCustomEvent", function(e, myName, myValue){
$(this).text(myName + ", hi there!");
$("span").stop().css("opacity", 1)
.text("myName = " + myName)
.fadeIn(30).fadeOut(1000);
});
$("button").click(function () {
$("p").trigger("myCustomEvent", [ "John" ]);
});
</script>
</body>
</html>Demo:
Example: Bind multiple events simultaneously.
$("div.test").bind({
click: function(){
$(this).addClass("active");
},
mouseenter: function(){
$(this).addClass("inside");
},
mouseleave: function(){
$(this).removeClass("inside");
}
});