jQuery mousestop event

JavaScript's onmouseover/onmouseenter event can often be too eager in that it'll fire even if your cursor just incidentally enters an element whilst moving to another area of the page. This is acceptable in the case of button rollover effects or any other unobtrusive actions but when it comes to more consequential actions it can, in some cases, be disruptive to the UX.

I've therefore written a mousestop event using jQuery's relatively un-touted special event API.

The example below demonstrates the difference between mouseenter and mousestop:

As you can see the mousestop event isn't fired until the mouse, well, stops. The event can be bound in the same way you would any other event:

$('#box').bind('mousestop', function() {
	// do stuff here
});

It can then be unbound like this:

$('#box').unbind('mousestop');

I've also included a shorthand method to keep the API in line with other jQuery events:

$('#box').mousestop(function() {
	// do stuff here
});

Thanks to jQuery’s special event API the event object is passed to the first parameter just like native events.

I've also made the sensitivity of the event (i.e. the amount of time the mouse needs to be stationary before the event is fired) global so it can be changed by adjusting the value of $.mousestopDelay in milliseconds:

$.mousestopDelay = 1000; // defaults to 50

This sensitivity can also be adjusted on a per element basis by passing a Number into the bind() or mousestop() methods:

$('#box-1').bind('mousestop', 1000, fn);
$('#box-1').mousestop(1000, fn);

As this only uses the setup() and teardown() methods it’ll work with jQuery 1.3+. For more information on compatibility and the special event API in general Ben Alman's write-up is well worth a read.

Comments

Feel free to use basic HTML to format your comment.

  • 94

    arijit says:

    26.01.2011

    Hello, this is a great tool and exactly what I was looking for.  Many thanks! One question: I need to get the mouse position on stop. Normally I would do this via e.pageX.  In this case, it would look something like$("#mydiv").mousestop(50, function(e) {  if (e.pageX > 500){    //do some stuff  }});But it looks like mousestop is not allowing that method, and I get an undefined for e.pageX.  I'm not adept enough at javascript to figure out why.  Any help is greatly appreciated!Thanks :)

  • 95

    Arijit says:

    26.01.2011

    Hello!  Just following up on the question I posted yesterday.  Ran a simple test on your demo: jQuery(document).ready(function($) { $('#box-1').mouseenter(function(e) { alert('mouse entered '+e.pageX); }); $('#box-2').mousestop(function(e) { alert('mouse stopped '+e.pageX); }); });As you will see, add the 'e' to mouseenter produces the expected result, but adding it to mousestop breaks the function.  I'll see if I can figure out why that is, but I'm a complete amateur at this.Thanks!

  • 113

    Guen44 says:

    13.04.2011

    Hi,This plugin works fine but I've exactly the same problem as Arijit concerning  pageX & pageY on mousestop event. e.pageX and e.pageY return the coordonates correctly on mousemove but the result becomes undefined using mousestop. Anyone has an idea to solve this problem. Many thanks

  • 202

    Doster says:

    29.09.2011

    Thanks you soooo much for this! Just what I was looking for. Keep up all the hard work!

  • 220

    Souvick says:

    26.10.2011

    I have a jcarousel image slider in my web page.all the images are coming dynamically. And when I mouse stop in any image that image displays in small popup(as in google NEWS section). I have used your jquery mouse stop event plugin API. No doubt its very good but I am facing a problem.when I mousestop on the image somtimes it display the image and sometimes not.can U tell me why this is happening??

  • 506

    Stan says:

    26.03.2012

    for those that asked or more for those that are still looking. the easy way that I found to get the cursor position on stop is to assign the variable first:$(document).mousemove(function(e) {thispageX =e.pageX;thispageY =e.pageY; });   $(document).mousestop(function() {$('#status').append('~'+thispageX +', '+ thispageY);   });Hope that helps!