Mouse Events

These events are triggered by mouse movement and button presses.

.mousedown()

Binds an event handler to the mousedown JavaScript event, or triggers that event on an element.

.mousedown(handler)
.mousedown()

The jQuery object, for chaining purposes.

This handler is a shortcut for .bind('mousedown', handler) in the first variation, and .trigger('mousedown') in the second.

The mousedown event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed. Any HTML element can receive this event.

For example, consider the HTML:

<div class="target button">Click Here</div>
<div class="trigger button">Trigger</div>

The event handler can be bound to the target button:

$('.target').mousedown(function() {
  $(this).log('Mousedown event was triggered.');
});

Now if we click on the target button, the message is displayed. We can also trigger the event when the second button is clicked:

$('.trigger').click(function() {
  $('.target').mousedown();
});

After this code executes, clicks on the trigger button will also display the message.

The mousedown event is sent when any mouse button is clicked. To act only on specific buttons, we can use the event object's which property in Mozilla browsers (1 for left button, 2 for middle button, 3 for right button), or the button property in Internet Explorer (1 for left button, 4 for middle button, 2 for right button). This is primarily useful for ensuring that the primary button was used to begin a drag operation; if ignored, strange results can occur when the user attempts to use a context menu. While the middle and right buttons can be detected with these properties, this is not reliable. In Opera and Safari, for example, right mouse button clicks are not detectable by default.

If the user clicks on an element, then drags the mouse pointer away from it or releases the button, this is still counted as a mousedown event. This sequence of actions is treated as a canceling of the button press in most user interfaces, so it is usually better to use the click event unless we know that the mousedown event is preferable for a particular situation.

.mouseup()

Binds an event handler to the mouseup JavaScript event, or triggers that event on an element.

.mouseup(handler)
.mouseup()

The jQuery object, for chaining purposes.

This handler is a shortcut for .bind('mouseup', handler) in the first variation, and .trigger('mouseup') in the second.

The mouseup event is sent to an element when the mouse pointer is over the element, and the mouse button is released. Any HTML element can receive this event.

For example, consider the HTML:

<div class="target button">Click Here</div>
<div class="trigger button">Trigger</div>

The event handler can be bound to the target button:

$('.target').mouseup(function() {
  $(this).log('Mouseup event was triggered.');
});

Now if we click on the target button, the message is displayed. We can also trigger the event when the second button is clicked:

$('.trigger').click(function() {
  $('.target').mouseup();
});

After this code executes, clicking the Trigger button will also display the message.

If the user clicks outside an element, drags onto it, and releases the button, this is still counted as a mouseup event. This sequence of actions is not treated as a button press in most user interfaces, so it is usually better to use the click event unless we know that the mouseup event is preferable for a particular situation.

.click()

Binds an event handler to the click JavaScript event, or triggers that event on an element.

.click(handler)
.click()

The jQuery object, for chaining purposes.

This handler is a shortcut for .bind('click', handler) in the first variation, and .trigger('click') in the second.

The click event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed and released. Any HTML element can receive this event.

For example, consider the HTML:

<div class="target button">Click Here</div>
<div class="trigger button">Trigger</div>

The event handler can be bound to the target button:

$('.target').click(function() {
  $(this).log('Click event was triggered.');
});

Now if we click on the target button, the message is displayed. We can also trigger the event when the second button is clicked:

$('.trigger').click(function() {
  $('.target').click();
});

After this code executes, clicking the trigger button will also display the message.

The click event is only triggered after this exact series of events:

This is usually the desired sequence before taking an action. If this is not required, the mousedown or mouseup event may be more suitable.

.dblclick()

Binds an event handler to the dblclick JavaScript event, or triggers that event on an element.

.dblclick(handler)
.dblclick()

The jQuery object, for chaining purposes.

This handler is a shortcut for .bind('dblclick', handler) in the first variation, and .trigger('dblclick') in the second.

The dblclick event is sent to an element when the element is double‑clicked. Any HTML element can receive this event.

For example, consider the HTML:

<div class="target button">Click Here</div>
<div class="trigger button">Trigger</div>

The event handler can be bound to the target button:

$('.target').dblclick(function() {
  $(this).log('Dblclick event was triggered.');
});

Now if we double-click on the target button, the message is displayed. We can also trigger the event when the second button is clicked:

$('.trigger').click(function() {
  $('.target').dblclick();
});

After this code executes, clicking the Trigger button will also display the message.

The dblclick event is only triggered after this exact series of events:

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 and others only one. If an interface that reacts differently to single and double clicks cannot be avoided, then the dblclick event should be simulated within the click handler. We can achieve this by saving a timestamp in the handler, and then comparing the current time to the saved timestamp on subsequent clicks. If the difference is small enough, we can treat the click as a double-click.

.toggle()

Binds two event handlers to the matched elements, to be executed on alternate clicks.

.toggle(handlerEven, handlerOdd)

The jQuery object, for chaining purposes.

The .toggle() method binds a handler for the click event, so the rules outlined for the triggering of click apply here as well.

For example, consider the HTML:

<div class="target button">Click Here</div>

The event handlers can be bound to this button:

$('.target').toggle(function() {
  $(this).log('Toggle event was triggered (handler 1).');
}, function() {
  $(this).log('Toggle event was triggered (handler 2).');
});

The first time the button is clicked, the first handler will be executed. The second time, the second handler will execute. Subsequent clicks will cycle between the two handlers.

The .toggle() method is provided for convenience. It is relatively straightforward to implement the same behavior by hand, and this can be necessary if the assumptions built into .toggle() prove limiting. For example, .toggle() is not guaranteed to work correctly if applied twice to the same element. Since .toggle() internally uses a click handler to do its work, we must unbind click to remove a behavior attached with .toggle(), so other click handlers can be caught in the crossfire. The implementation also calls .preventDefault() on the event, so links will not be followed and buttons will not be clicked if .toggle() has been called on the element.

.mouseover()

Binds an event handler to the mouseover JavaScript event, or triggers that event on an element.

.mouseover(handler)
.mouseover()

The jQuery object, for chaining purposes.

This handler is a shortcut for .bind('mouseover', handler) in the first variation, and .trigger('mouseover') in the second.

The mouseover event is sent to an element when the mouse pointer enters the element. Any HTML element can receive this event.

For example, consider the HTML:

<div class="target button">Move Here</div>
<div class="trigger button">Trigger</div>

The event handler can be bound to the target button:

$('.target').mouseover(function() {
  $(this).log('Mouseover event was triggered.');
});

Now when the mouse pointer moves over the target button, the message is displayed. We can also trigger the event when the second button is clicked:

$('.trigger').click(function() {
  $('.target').mouseover();
});

After this code executes, clicking the Trigger button will also display the message.

This event type can cause many headaches due to event bubbling. When the mouse pointer moves over a nested element, a mouseover event will be sent to that, then trickle up the hierarchy. This can trigger our bound mouseover handler at inopportune times. By using the .hover() method instead, we can avoid this problem.

.mouseout()

Bind an event handler to the mouseout JavaScript event, or trigger that event on an element.

.mouseout(handler)
.mouseout()

The jQuery object, for chaining purposes.

This handler is a shortcut for .bind('mouseout', handler) in the first variation, and .trigger('mouseout') in the second.

The mouseout event is sent to an element when the mouse pointer leaves the element. Any HTML element can receive this event.

For example, consider the HTML:

<div class="target button">Move Here</div>
<div class="trigger button">Trigger</div>

The event handler can be bound to the target button:

$('.target').mouseout(function() {
  $(this).log('Mouseout event was triggered.');
});

Now when the mouse pointer moves out of the target button, the message is displayed. We can also trigger the event when the second button is clicked:

$('.trigger').click(function() {
  $('.target').mouseout();
});

After this code executes, clicking the Trigger button will also display the message.

This event type can cause many headaches due to event bubbling. When the mouse pointer moves out of a nested element, a mouseout event will be sent to that, then trickle up the hierarchy. This can trigger our bound mouseout handler at inopportune times. By using the .hover() method instead, we can avoid this problem.

.hover()

Binds two event handlers to the matched elements, to be executed when the mouse pointer enters and leaves the elements.

.hover(handlerIn, handlerOut)

The jQuery object, for chaining purposes.

The .hover() method binds handlers for both mouseover and mouseout events. We can use it to simply apply behavior to an element during the time the mouse is within the element. Consider the HTML:

<div class="target button">Move Here</div>

Now we can bind handlers to both entering the element and leaving it with a single method call:

$('.target').hover(function() {
  $(this).log('Hover event was triggered (entering).');
}, function() {
  $(this).log('Hover event was triggered (leaving).');
});

Now the first message will be displayed when the mouse pointer enters the element, and the second will be displayed when the mouse pointer leaves.

With the mouseover and mouseout events, it is common to receive false positives due to event bubbling. When the mouse pointer crosses over a nested element, the events are generated and will bubble up to the parent element. The .hover() method incorporates code to check for this situation and do nothing, so we can safely ignore this problem when using the .hover() shortcut.

.mousemove()

Binds an event handler to the mousemove JavaScript event, or triggers that event on an element.

.mousemove(handler)
.mousemove()

The jQuery object, for chaining purposes.

This handler is a shortcut for .bind('mousemove', handler) in the first variation, and .trigger('mousemove') in the second.

The mousemove event is sent to an element when the mouse pointer moves inside the element. Any HTML element can receive this event.

For example, consider the HTML:

<div class="target button">Move Here</div>
<div class="trigger button">Trigger</div>

The event handler can be bound to the target button:

$('.target').mousemove(function() {
  $(this).log('Mousemove event was triggered.');
});

Now when the mouse pointer moves within the target button, the message is displayed. We can also trigger the event when the second button is clicked:

$('.trigger').click(function() {
  $('.target').mousemove();
});

After this code executes, clicking the Trigger button will also display the message.

When tracking the mouse movement, we usually clearly need to know the actual position of the mouse pointer. The event object that is passed to the handler contains some information about the mouse coordinates. Properties such as .clientX, .offsetX, and .pageX are available, but support for them differs between browsers. Fortunately, jQuery normalizes the .pageX and .pageY attributes so that they can be used in all browsers. These attributes provide the X and Y coordinates of the mouse pointer relative to the top‑left corner of the page.

We need to remember that the mousemove event is triggered whenever the mouse pointer moves, even for a pixel. This means that hundreds of events can be generated over a very small amount of time. If the handler has to do any significant processing, or if multiple handlers for the event exist, this can be a serious performance drain on the browser. It is important, therefore, to optimize mousemove handlers as much as possible, and to unbind them as soon as they are no longer needed.

A common pattern is to bind the mousemove handler from within a mousedown hander, and to unbind it from a corresponding mouseup handler. If implementing this sequence of events, remember that the mouseup event might be sent to a different HTML element than the mousemove event was. To account for this, the mouseup handler should typically be bound to an element high up in the DOM tree, such as <body>.