# hoverIntent jQuery Plugin

## 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...

https://github.com/briancherne/jquery-hoverIntent

## Examples

### jQuery's .hover() ... for reference

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

- hover ignores over/out events from children

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 also ignores over/out events from children

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 only 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 a modern version of jQuery and hoverIntent, 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 grey paragraph).
However, if you were using Google Chrome and if this page were using jQuery 1.5 (or earlier) and hoverIntent r5 (or earlier), 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.

## Release History

- All newer releases
- v1.9.0 = (2015, 2017) Refactored plugin to fix a long-standing bug that prevented multiple instances of the plugin to be active on the same element. Exports plugin as an AMD module so it can be used with AMD loaders. The `pageX` and `pageY` properties of the event passed to the "over" handler now reflect current mouse position. Note that this may be a breaking change for some; if your "over" handler requires the unmodified coordinates from original mouseover, you can read them from the `event.originalEvent`. Many other improvements and bug fixes.
- v1.8.1 = (2014) Minor update: fixes bower.json to indicate that the plugin works with all versions of jQuery >= 1.9.1.
- v1.8.0 = (2014) Changed to Semantic Versioning (from r8 to v1.8.0). Removed U+FEFF character from beginning of JS file. Removed stray "jQuery" in favor of "$" for noConflict situations. Changed measurements to use Euclidean (instead of rectilinear) distance. Thanks to the GitHub community for patches, suggestions, and fixes!
- r7 = (2013) Added event delegation via "selector" param/property. Added namespaced events for better isolation. Added handlerInOut support.
- r6 = (2011) Identical to r5 except that the Google Chrome defect is fixed once you upgrade to jQuery 1.5.1 (or later).
- r5 = (2007) Added state to prevent unmatched function calls. This and previous releases suffer 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 onMouseLeave function call. Fixed two-interval mouseOver bug (now setting pX and pY onMouseEnter instead of hardcoded value).
- r1 = Initial release to jQuery discussion forum for feedback.