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) 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.
Download hoverIntent r6 (fully-commented, uncompressed)
Download hoverIntent r6 (minified)
hoverIntent r6 (2011) has all the same functionality of r5 (2007) except that the Google Chrome defect (known defects) is fixed once you upgrade to jQuery 1.5.1.
Translations
Беxарусaая courtesy Martha Ruszkowski
Examples
jQuery's hover (for reference)
$("#demo1 li").hover( makeTall, makeShort ) - hover ignores over/out events from children
jQuery's built-in hover calls onMouseOver/onMouseOut functions immediately.
hoverIntent as hover replacement
$("#demo2 li").hoverIntent( makeTall, makeShort ) - hoverIntent also ignores over/out events from children
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 = {
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.
Basic Configuration Options
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.
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.
Advanced Configuration Options
When choosing the default settings for hoverIntent I tried to find the best possible balance between responsiveness and frequency of false positives. Modify these if you are brave, test tirelessly, and completely understand what you are doing.
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
Notice of DOM Manipulation
hoverIntent adds two custom attributes to every DOM element it's assigned to. For example: <li hoverIntent_t="" hoverIntent_s="">
- hoverIntent_t is the polling interval timer, or the mouseOut timer.
- hoverIntent_s stores the state to prevent unmatched function calls.
Timers are stored as integers, so there should not be any trouble with memory leaks. hoverIntent state is also stored as an integer.
Known Defects
hoverIntent r5 suffers from a defect in Google Chrome that improperly triggers mouseout when entering a child input[type="text"] element. hoverIntent r6 uses the same mouseenter/mouseleave special events as jQuery's built-in hover, and jQuery 1.5.1 patched this issue. Thanks to Colin Stuart for tipping me off about this and for providing isolated code to demonstrate/test.
This page uses jQuery 1.5.1+ and hoverIntent r6, so when your cursor goes over the text input nothing should change (it should continue to read "enter parent" because you are still over this paragraph).
However, if you were using Google Chrome and if this page were using an older version of jQuery or hoverIntent, moving the cursor over the text input would improperly trigger the mouseout event, and the value would change to "leave parent".
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.
jQuery's hover can take both a handlerIn and a handlerOut or just a handlerIn. The current version of hoverIntent requires both handlerIn and handlerOut or a single configuration object. It was not designed to take just a handlerIn like hover. This will be addressed in a future release.
Please email me ( brian@cherne.net ) if you have questions or would like to notify me of any defects. I will tweet about any updates from @briancherne using the tags #hoverIntent #jQuery.
The Future of hoverIntent
hoverIntent r7 (in development) will be backwards compatible with all current implementations and include hoverIntent custom events.
Release History
- r7 = In development. Adding custom events.
- r6 = Current stable release. Updated to correct for Google Chrome defect.
- r5 = Added state to prevent unmatched function calls. This release (and previous releases) suffers from a defect in Google Chrome that improperly triggers mouseout when entering a child input[type=text] element.
- r4 = Fixed polling interval timing issue (now uses a self-calling timeout to avoid interval irregularities).
- r3 = Developer-only release for debugging.
- r2 = Added timeout and interval references to DOM object -- keeps timers separate from each other. Added configurable options. Added timeout option to delay onMouseOut function call. Fixed two-interval mouseOver bug (now setting pX and pY onMouseOver instead of hardcoded value).
- r1 = Initial release to jQuery discussion forum for feedback.