Writing a Mousestop Event Plugin Using jQuery

I recently published a jQuery tooltip plugin of my own that was pretty simple, it basically popped up when you hovered over an element, nothing fancy. However I noticed the default browser had a bit of a delay before it actually shows up. It also won’t show up until you stop moving your mouse around on the element. Lastly there was only a certain amount of time you had to stop moving your mouse before the tooltip didn’t appear at all.

I wanted to rebuild this functionality and ended up writing my own little mousestop event plugin in jQuery which I thought I would share. It’s a pretty simple little piece of code that basically triggers when a mouse stops over a certain element with a few options for the timers.

You can check out documentation on it here: jQuery mousestop plugin
Also check it out in action with my tooltip plugin here: jQuery tooltip plugin

1. The mouse stop event

First we just want to know how to detect a mouse stop, this is actually pretty easy and only requires a single timer to constantly loop until enough delay has occurred.

var movementTimer = null;

    $("#element").mousemove(function(e)
    {
    	clearTimeout(movementTimer);
    	movementTimer = setTimeout(function()
    	{
    		//do something here
    	}, 300);
    })

2. Stopping the Timer on Mouseout

We have our mousestop working, but now what happens when we mouseout of the element? We wouldn’t want mousestop event to trigger, since we are technically not stopping on the element. All we need to do here is add a mouseout event that clears our timer to make sure it doesn’t get executed.

var movementTimer = null;

    $("#element").mouseout(function(e)
    {
    	clearTimeout(movementTimer);
    })

3. Setting the Grace Period

Here is where it starts getting tricker. If we want to set an amount of time that the mousestop event has to trigger before it’s completely turned off, we will need to introduce a second timer.

var counter = 0;
    var counterMax = 20;
    var movement = false;

    elem
    .mouseover(function(e)
    {
    	movement = true;
    	
    	//check if movement has stopped to a maximum time of 100*counterMax, after that event will not run at all unless you re-mouseover
    	displayTimer = setInterval(function()
    	{
    		counter++;
    		
    		if(counter 4. Getting Proper Coordinates
There is one more crucial piece here that we need to add. Since we are running this from the mouseover event, our event.pageX and event.pageY coordinates will be from where they entered the element, however we will probably want the mouse position of where it is now while the mouse is moving around.

[js]
    var x = null;
    var y = null;

    var movementTimer = null;

    $("#element").mousemove(function(e)
    {
    	x = e.pageX;
    	y = e.pageY;
    })

5. Putting It All Together

We can now put this all together into a plugin like below. This little jQuery plugin has less than 100 lines of code, and is less than 1KB in size when minified.

(function($)
{
var defaultSettings =
{
timeToStop : null, // the amount of time the stop even thas to run before it will not run at all anymore
delayToStop : ‘300’, // the delay for what is considered a “stop”
onMouseout : null, // function to run when we mouseout of our element
onStopMove : null // function to run when we start moving again after the stop
};

$.fn.mousestop = function(func, settings)
{
settings = $.extend({}, defaultSettings, settings || {});

return this.each(function()
{
var elem = $(this);

var movement = false;

var displayTimer = null
var movementTimer = null;

//only need this piece if there is a time limit on when the mouse stop can occur.
if(settings.timeToStop != null)
{
var x = null;
var y = null;

var counter = 0;
var counterMax = Math.ceil(settings.timeToStop / 100);

elem
.mouseover(function(e)
{
movement = true;

//check if movement has stopped to a maximum time of 100*counterMax, after that event will not run at all unless you re-mouseover
displayTimer = setInterval(function()
{
counter++;

if(counter About the Author

Robert Nova is a web developer with a particular interest in jQuery plugins and finding ways to help developers build their projects as quickly as possible. He is founder of www.websanova.com, a site dedicated to jQuery plugins and other entrepreneurial resources.