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 is similar to jQuery's hover method. However, instead of calling the handlerIn function immediately, hoverIntent 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. That's where hoverIntent comes in...

Examples

jQuery's hover (for reference)

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

jQuery's built-in hover calls handlerIn and handlerOut functions immediately. If you move your cursor back and forth quickly across the tiles you'll see how the immediate execution can lead to problems.

.hoverIntent( handlerIn, handlerOut )

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

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

.hoverIntent( handlerInOut )

$("#demo3 li").hoverIntent( toggleHeight );

hoverIntent can also take a single handlerInOut, just like jQuery's hover.

.hoverIntent( handlerIn, handlerOut, selector )

$("#demo4").hoverIntent( makeTall, makeShort, 'li' );

Unlike jQuery's hover, hoverIntent supports event delegation! Just pass in a selector of a descendant element.

.hoverIntent( handlerInOut, selector )

$("#demo5").hoverIntent( toggleHeight, 'li' );

Unlike jQuery's hover, hoverIntent supports event delegation with handlerInOut.

.hoverIntent( object )

$("#demo6").hoverIntent({
    over: makeTall,
    out: makeShort,
    selector: 'li'
});

To control hoverIntent more precisely and override the default configuration options, pass it an object as the first parameter. The object must at least contain an "over" function. If the "over" function is sent alone, it will act just like handlerInOut.

Common Configuration Options

These are the common options you'll want to use. Note, nothing prevents you from sending an empty function as the handlerIn or handlerOut functions.

over:

Required. The handlerIn function you'd like to call on "mouseenter with intent". Your function receives the same "this" and "event" objects as it would from jQuery's hover method. If the "over" function is sent alone (without "out") then it will be used in both cases like the handlerInOut param.

out:

The handlerOut function you'd like to call on "mouseleave after timeout". 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.

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

selector:

A selector string for event delegation. Used to filter the descendants of the selected elements that trigger the event. If the selector is null or omitted, the event is always triggered when it reaches the selected element. Read jQuery's API Documentation for the .on() method for more information.

Advanced Configuration Options

Modify these if you are brave, test tirelessly, and completely understand what you are doing. When choosing the default settings for hoverIntent I tried to find the best possible balance between responsiveness and frequency of false positives.

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. Note that hoverIntent r7 and earlier perform this comparison using rectilinear distance, whereas more recent versions compare against euclidean (straight-line) distance for better accuracy and intuition. If you are upgrading from an older version, you may want to verify that the desired behavior is preserved. Default sensitivity: 6

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

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.9.1 and hoverIntent r7, 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 flush against the edge of the browser chrome, sometimes Internet Explorer does not trigger a "mouseleave" event if your cursor leaves the element/browser in that direction. hoverIntent cannot correct for this.

Please email me brian(at)cherne(dot)net if you have questions or would like to notify me of any defects.

Release History