What is hoverIntent?

hoverIntent is a plug-in that attempts to determine the user's intent... like a crystal ball, only with mouse movement! It works like (and was derived from) jQuery's built-in hover. However, instead of immediately calling the onMouseOver function, it waits until the user's mouse slows down enough before making the call.

Why? To delay or prevent the accidental firing of animations or ajax calls. Simple timeouts work for small areas, but if your target area is large it may execute regardless of intent. Also, because jQuery animations cannot be stopped once they've started it's best not to start them prematurely.

Download hoverIntent (fully-commented, uncompressed)

Download hoverIntent (minified)

Examples

jQuery's hover (for reference)

$("#demo1 li").hover( makeTall, makeShort )

jQuery's built-in hover calls onMouseOver/onMouseOut functions immediately.

hoverIntent as hover replacement

$("#demo2 li").hoverIntent( makeTall, makeShort )

hoverIntent is interchangeable with jQuery's hover. It can use the same exact onMouseOver and onMouseOut functions and it passes the same this and event objects to those functions.

hoverIntent with configuration object

var config = {    
     sensitivity: 3, // number = sensitivity threshold (must be 1 or higher)    
     interval: 200, // number = milliseconds for onMouseOver polling interval    
     over: makeTall, // function = onMouseOver callback (REQUIRED)    
     timeout: 500, // number = milliseconds delay before onMouseOut    
     out: makeShort // function = onMouseOut callback (REQUIRED)    
};

$("#demo3 li").hoverIntent( config )

To override the default configuration of hoverIntent, pass it an object as the first (and only) parameter. The object must contain "over" and "out" functions, in addition to any other options you'd like to override.

Configuration Options

When choosing the default settings for hoverIntent I tried to find the best possible balance between responsiveness and frequency of false positives. The "timeout" delay (by default set to 0) will mostly likely be the one you'll want to override. The "over" and "out" functions are required but nothing prevents you from sending an empty function(){} to either.

sensitivity:

If the mouse travels fewer than this number of pixels between polling intervals, then the "over" function will be called. With the minimum sensitivity threshold of 1, the mouse must not move between polling intervals. With higher sensitivity thresholds you are more likely to receive a false positive. Default sensitivity: 7

interval:

The number of milliseconds hoverIntent waits between reading/comparing mouse coordinates. When the user's mouse first enters the element its coordinates are recorded. The soonest the "over" function can be called is after a single polling interval. Setting the polling interval higher will increase the delay before the first possible "over" call, but also increases the time to the next point of comparison. Default interval: 100

over:

Required. The function you'd like to call onMouseOver. Your function receives the same "this" and "event" objects as it would from jQuery's hover method.

timeout:

A simple delay, in milliseconds, before the "out" function is called. If the user mouses back over the element before the timeout has expired the "out" function will not be called (nor will the "over" function be called). This is primarily to protect against sloppy/human mousing trajectories that temporarily (and unintentionally) take the user off of the target element... giving them time to return. Default timeout: 0

out:

Required. The function you'd like to call onMouseOut. Your function receives the same "this" and "event" objects as it would from jQuery's hover method. Note, hoverIntent will only call the "out" function if the "over" function has been called on that same run.

Notice of DOM Manipulation

hoverIntent adds two custom attributes to every DOM element it's assigned to. For example: <li hoverIntent_t="" hoverIntent_s="">

Timers are stored as integers, so there should not be any trouble with memory leaks. hoverIntent state is also stored as an integer.

Known Bugs

If you place an element with onMouseOut event listeners flush against the edge of the browser chrome, sometimes Internet Explorer does not trigger an onMouseOut event immediately if your mouse leaves the document. hoverIntent does not correct for this.

Is it a bug or a feature? Because .hover() and .hoverIntent() both ignore over/out events from children nodes (using "return false") this also prevents the statusbar readout of nested anchor tag hrefs. No known fix for this is known at this time.

Please contact me ( brian@cherne.net ) if you'd like to be notified directly of any bugs/fixes/updates. Announcements will also be made on the jQuery (English) Google Group.

Release History