What is hoverIntent?

hoverIntent is a function 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 returns the same this and event objects to those functions.

hoverIntent (with configuration object)

var config = {    
     sensitivity: 1, // number = sensitivity threshold (must be 1 or higher)    
     interval: 750, // number = milliseconds for onMouseOver polling interval    
     over: makeTall, // function = onMouseOver callback (REQUIRED)    
     timeout: 750, // 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.

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