MouseIntent jQuery Plug-in
Overview
The MouseIntent jQuery plug-in was designed to improve mouse movement usability by providing a way to try and detect a user's intent when mousing away from an element. There is a common usability issue where a user may accidentally "overshoot" an element. If you rely on traditional mouse events ("mouseout" or "mouseleave"), the problem is, as soon as the user mouses away from the element, your events are triggered. This can cause problems any time you have options that can hide when the event is triggered and can cause frustration on the user's end.
The MouseIntent plugin aims to help resolve this problem by measuring the user's intent. If the user quickly moves away from an element, but then moves back into the element, the element will not throw a "mouseaway" event. For example, you may have a menu that hides on mouseout, but you don't want the menu to disappear if the user accidentally moves their mouse just slightly outside the menu area. The plugin can help prevent that from happening so the user doesn't have to move the mouse and/or click to re-open the menu.
Requirements
In order to use the MouseIntent plug-in, you need the following:
- jQuery v1.7.2 (or higher)
- jquery.mouseintent.js Plug-in
Features
- Allows for flexibility for how wide the border around the element is and how quickly a pause in mouse movement will cause the mouseout event.
- Custom event handlers
- Detach/attach MouseIntent behavior from the element
Usage
To use MouseIntent, you can bind it to a mouse interaction event of your page elements. For example:
$("#id").bind("mouseenter", function(){
$(this).mouseintent([options]);
});You can use any selector that will target input elements on your page where you require a delay in the mouseout event if the mouse is indeed moved off the target.
Arguments
- options
-
This argument is optional and allows you to customize the settings used for each instance of the plug-in. For a list of all available options, see the Options section.
Now that we have a reference to the widget, we can invoke any of the public API calls.
Public API
- $("#id").mouseintent("destroy")
-
Destroys the MouseIntent widget.
- $("#id").mouseintent("mouseaway")
-
Manually triggers the "mouseaway" handlers.
- $("#id").mouseintent("mousereenter")
-
Manually triggers the "mousereenter" handlers.
- $("#id").mouseintent("updateDimensions")
-
Updates the instance's dimensions information to the element's current dimensions. This is only needed if the target object's dimensions have changed since the object was initialized.
Options
There are a number of options available for customizing handling of the widget.
{
borderThreshold: 100 // The distance (in pixels) from the element in
// which to measure mouse movement to determine
// the intent of the user. If the cursor is
// outside this border radius, then focus on
// the element will be automatically be removed.
// This can either be a single numeric value or
// an array defining TRBL (0 = top, 1 = right,
// 2 = bottom, 3 = left). Defaults to 100.
, monitorMovement: true // A boolean value which determines whether or not
// an element should still be considered in
// "focus" if the user is moving the mouse
// within the border threshold. Defaults to
// true.
, monitorFrequency: 100 // The frequency (in milliseconds) in how often we
// check to see if the mouse is still being
// moved in the border threshold. This value
// should be set to something lower than the
// mouseAwayAfter option. Setting the value too
// low can result in performance issues.
// Defaults to 100.
, mouseAwayAfter: 1500 // The maximum length of time (in milliseconds) to
// keep monitoring for mouse movement inside the
// threshold. Once this delay has been reached
// and the user has not moused back into the
// original element, the element will have been
// considered to be moused out. Defaults to
// 1500. Set to 0 to disable this feature. When
// disabled, as long as the user is moving the
// mouse in the border threshold, the element
// will be considered in focus.
// event handlers
, init: null // Runs when the plugin is initialized
, mouseaway: null // Runs when the mouse is determined to have left
// the element's border threshold
, mousereenter: null // Runs when the mouse is determined to have
// re-entered the original elements space
}Public Events
There are several public events that can be triggered.
- mouseintent-init
-
Runs when the plugin is initialized
- mouseintent.destroy
-
Runs when the plugin is destroyed
- mouseintent-mouseaway
-
Runs when the mouse is determined to have left the element's border threshold
- mouseintent-mousereenter
-
Runs when the mouse is determined to have re-entered the original elements space
Getting Started
The first thing we need to do is to load the required JavaScript libraries and the CSS stylesheet used by the widget:
<!---// load jQuery and the jQuery iButton Plug-in //--->
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script type="text/javascript" src="./lib/jquery.mouseintent.js"></script>Before you can invoke an instance of the MouseIntent widget, you must have one or more elements on your page.
<div id="menu1" class="menu"></div/>The next step is to actually create an instance of the MouseIntent widget. You want to make sure to initialize the widget after all the necessary DOM elements are available, which makes the document.ready event a great place to initialize the widget.
<script type="text/javascript">
$(document).ready(function (){
$("#menu1").bind("mouseenter", function(){
var $el = $(this);
$el.mouseintent({
init: function(){
$el.addClass("active"); // this turns the red box green
}
, mouseaway: function (){
$el.removeClass("active"); // this turns the green box red
}
})
});
});
</script>Now let us take a look at what the code above produced.
Example
You can try moving your mouse slightly outside the box and quickly back into the box, and you'll see the box maintains its focus.
For a more visual example, see the Giva Labs - MouseIntent Example Page page.
License
Copyright 2013 Giva (https://www.givainc.com/labs/) Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Revisions
- v1.0.00 (2013-10-03)
-
- Initial release
Download
The following download includes both uncompressed and minified versions of the plug-in and all the CSS and image files required to get you started. See the gettingstarted.htm file for usage instructions and a working example.
jquery.mouseintent.zip (13 KB)
