jQuery Events: Mouse Events
jQuery supports several mouse-related shorthand methods for capturing user actions associated with mouse. These methods are shorthand to the .on() method. We begin with a table that lists various mouse-related events along with a short description. The element that gets attached with the mouse event could be an anchor, an image or the window/document element itself.
| Event | Shorthand Method | Event Description |
|---|---|---|
| click | .click() | when we click the mouse. |
| dblclick | .dblclick() | when we double-click the mouse. |
| mousemove | .mousemove() | when we move the mouse. |
| mousedown | .mousedown() | when we hold the mouse button down. |
| mouseup | .mouseup() | when we release the previously held mouse button. |
| mouseenter | .mouseenter() | when the mouse pointer enters an element. |
| mouseleave | .mouseleave() | when the mouse pointer leaves an element. |
| hover | .hover() | combines mouseenter and mouseleave events. |
| mouseover | .mouseover() | when we move the mouse over an object. |
| mouseout | .mouseout() | when we move the mouse away from an object. |
| focusout | .focusout() | when the focus goes out of an element of its child elements. |
Let us now describe the above events.
The first two events click and dblclick are associated with a single click and double-click of the mouse, respectively. The third event in the table, mousemove event, is triggered when the mouse moves while it is on the element.
The next two events, mousedown and mouseup capture events related to pressing/releasing of the mouse button respectively. The mousedown is triggered when we press the mouse button down (either left or right) and mouseup is triggered when we release the previously pressed button.
The event mouseenter is triggered when the mouse goes over an element and is true as long as the mouse remains on that element. The mouseleave event is triggered when the mouse leaves that element. With the hover event, we can combine the mouseenter and mouseleave together in one shot.
Similar to the case of mouseenter/mouseleave, we also have mouseover/mouseout events. The event mouseover is triggered when the mouse goes over an element and is true as long as the mouse remains on that element. The mouseout event is triggered when the mouse leaves that element.
So, if mouseenter/mouseleave pair behaves similar to the mouseover/mouseout pair, then why do we need it? Well, the answer lies in the way they handle event bubbling. If we have an event-handler tied to an element, then the mouseover/mouseout pair would trigger even if we hit its child element. However, with mouseenter/mouseleave, the event will trigger only if we hit the outer element.
The focusout event occurs when we take the mouse away from the element. Typically, used with the focusin event, which happens when we focus a form element, the focusout event represents the case when an element loses focus.
All of the above methods, except focusout and hover methods, have three different signatures. We list them below. The first variant merely accepts the event-handler that gets triggered when the event happens. The second variant allows us to pass data -- this data would be available as eventObject.data value in the event handler function. These two variants are essentially short-cuts to the .on() method. The last variant, in fact, triggers the corresponding event and hence, is a short-cut for the .trigger() method.
.click(eventHandlerFunction(eventObject)); [Added in 1.0] .click(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .click(); [Added in 1.0] .dblclick(eventHandlerFunction(eventObject)); [Added in 1.0] .dblclick(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .dblclick(); [Added in 1.0] .mousemove(eventHandlerFunction(eventObject)); [Added in 1.0] .mousemove(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .mousemove(); [Added in 1.0] .mousedown(eventHandlerFunction(eventObject)); [Added in 1.0] .mousedown(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .mousedown(); [Added in 1.0] .mouseup(eventHandlerFunction(eventObject)); [Added in 1.0] .mouseup(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .mouseup(); [Added in 1.0] .mouseenter(eventHandlerFunction(eventObject)); [Added in 1.0] .mouseenter(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .mouseenter(); [Added in 1.0] .mouseleave(eventHandlerFunction(eventObject)); [Added in 1.0] .mouseleave(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .mouseleave(); [Added in 1.0] .mouseover(eventHandlerFunction(eventObject)); [Added in 1.0] .mouseover(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .mouseover(); [Added in 1.0] .mouseout(eventHandlerFunction(eventObject)); [Added in 1.0] .mouseout(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .mouseout(); [Added in 1.0]
In the next set, we provide the signatures of the .focusout() and the .hover() methods. The .focusout() method has two variants. The first variant, once again, accepts the event-handler that would get triggered when the event event happens. The second variant allows us to piggyback data -- this data would be available as eventObject.data value in the event handler function. These two variants are essentially short-cuts to the .on() method. The .hover() method accepts two handlers, one when the mouse enters an element (the mouseenter event) and the other when the mouse leaves the element (the mouseleave event).
.focusout(eventHandlerFunction(eventObject)); [Added in 1.4] .focusout(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .hover(eventHandlerInFunction(eventObject), eventHandlerOutFunction(eventObject)); [Added in 1.0]
Please note that one of the mouse events, .toggle() has been deprecated since jQuery 1.8 and was removed in jQuery 1.9.
Now that the basic introduction is out of our way, we provide below an example that binds various mouse events to the window object. The example handles these events and when they occur, it updates the text on the main page with the corresponding text from the handler functions. Here it is:
<!doctype html>
<html>
<head><h2>A Trivial Page</h2></head>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js">
</script>
<script type="text/javascript">
$(document).ready(function() {
// Attach an event-handler for a click event.
$(window).click(function(eventObject) {
$("body").append("<br>Mouse Click");
});
// Attach an event-handler for a double-click event.
$(window).dblclick(function(eventObject) {
$("body").append("<br>Double Mouse Click");
});
// Attach an event-handler for a mousedown event.
$(window).mousedown(function(eventObject) {
$("body").append("<br>Mouse Down");
});
// Attach an event-handler for a mouseup event.
$(window).mouseup(function(eventObject) {
$("body").append("<br>Mouse Up");
});
// Attach an event-handler for a mousemove event.
$(window).mousemove(function(eventObject) {
$("body").append("<br>Mouse Move");
});
});
</script>
</body>
</html>
Here is the browser output when we trigger various mouse events on the window. Please note that we could have also added these events to the document object instead of the body object and the output would have been same as before.
Figure: Mouse events for window
If we wanted to add mouse events to other HTML elements, then we can do this similarly. In the following example, we show adding two mouse-events -- mouseover and mouseout events -- to an anchor element. With this example, when we hover the mouse over the anchor or when we move the mouse out of the anchor, then the corresponding text is added on the page.
<!doctype html>
<html>
<head><h2>A Trivial Page</h2></head>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js">
</script>
<a href="http://www.nobelprize.org" id="idAnchor"> Nobel Prize Winners! </a>
<script type="text/javascript">
$(document).ready(function() {
// Attach an event-handler for a mouseout event.
$("#idAnchor").mouseover(function() {
$("body").append("<br>Mouse Over");
});
// Attach an event-handler for a mouseout event.
$("#idAnchor").mouseout(function() {
$("body").append("<br>Mouse Out");
});
// Attach an event-handler for a mouseenter event.
$("#idAnchor").mouseenter(function() {
$("body").append("<br>Mouse Enter");
});
// Attach an event-handler for a mouseleave event.
$("#idAnchor").mouseleave(function() {
$("body").append("<br>Mouse Leave");
});
});
</script>
</body>
</html>
Here is the browser output when we move the mouse over the anchor link.
Figure: Mouse events for an anchor