jquery.mousehover
This event-subscribing jQuery plugin behaves like jQuery.hover
, as long as the real mouse is used. If the mouseenter
and mouseleave
events are emulated by other input device, jQuery.mousehover
does not trigger the event handlers.
Motivation
Although mobile devices do not support mouse as an input device, they trigger mouse-specific events, when your finger touches the display. These emulated events include mouseenter
and mouseleave
, which trigger event handlers registered by jQuery.hover
. It may not be a problem, if you follow the best practice and do not use JavaScript hover handling at all, or perform visual enhancements only inside the event handlers. Otherwise you will face:
- Double-tap issue caused by having the first tap act as
hover
and the second one asclick
. - Showing call-outs, context menus, toolbars or other interactive controls on touch and not being able to get rid of them easily. Not all devices fire
mouseleave
aftermouseenter
and end the chain of events withclick
.
If you write an interface for devices capable of using multiple input devices like mouse, pen and touch, and you need to ensure, that part of that interface will work only if the input device is a real mouse, the plain jQuery.hover
handler will not be enough. The jQuery.mousehover
plugin allows you for safe mouse event listening, without you coding the real mouse detection.
Synopsis
$(selector).mousehover(handlerIn, handlerOut, options); $(selector).mousehover('off', options);
Binds one or two handlers to the selected elements, which will be executed, when the real mouse pointer enters and leaves the elements. Ignores the emulated hover effect caused by tapping on a touch display. It calls jQuery.on
for selected events needed for the reliable operation.
See the original documentation for jQuery.hover
for more information.
Parameters
Name | Type | Description |
---|---|---|
handlerIn | Function(Event event) | A function to execute when the mouse pointer enters the selected element. |
handlerOut | Function(Event event) | A function to execute when the mouse pointer leaves the selected element. |
options | Object | An object with extra parameters for the plugin or its method execution. |
The parameter handlerIn
has to be provided, if you are not unregistering the event handlers by passing the methof name off
instead of it. The parameter handlerOut
is optional; if not provided, the event handler handlerIn
will be used instead of it. The options
parameter is optional.
Except for pasing the parameters as a list to the plugin function, you can pass them to it as an object literal too.
$(selector).mousehover({ handlerIn: handlerIn, handlerOut: handlerOut, options: { namespace: 'menu' } });
Methods
noConflict() : jQuery.mousehover
Restores the earlier mousehover plugin, which had been registered in jQuery before this one. This plugin is returned for explicit usage.
var mousehover = $.fn.mousehover.noConflict(); mousehover.call($(selector), handlerIn, handlerOut, options);
off : jQuery
Unsubscribes event handlers registered by the previous call to mousehover
. It calls jQuery.off
for the events used during the registration time.
$(selector).mousehover('off', options);
Options
namespace : string
Registers event handlers for mousehover
using the specified namespace. If other code registers mouseenter
, mouseleave
, touchend
, pointerenter
and pointerleave
events, namespacing allows for selective unregistration of the particular event handlers. If you want to make sure, that you do not affect other plugins, you should use a unique namespace for mousehover
. No namespace is used by default.
$(selector).mousehover(handlerIn, handlerOut, {namespace: 'menu'}); $(selector).mousehover('off', {namespace: 'menu'});
Usage
You have to ensure, that jQuery
is included earlier, than jquery.mousehover.js
. The slim version of jQuery is enough.
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script> <script src="jquery.mousehover.min.js" integrity="sha384-SQjNFjqu6aB5MdZehH5H2s+HipiAfjmg6BCwBESCcxoACk1XN8j8UAzbrGL8M64J" crossorigin="anonymous"></script>
If you use RequireJS or other AMD module loader, you have to ensure, that the jquery
module is mapped correctly. The jquery.mousehover
module will load the jquery
module as its dependency automatically.
<script> require.config({ paths: { jquery: 'https://code.jquery.com/jquery-3.2.1.slim.min.js' } }); require('jquery', 'jquery.mousehover', function ($) { }); </script>
If you use CommonJS and compile your project to be loadable in the web browser or other AMD module loader, you can install jquery
and jquery.mousehover
as NPM
or Bower
modules.
var $ = require('jquery'); require('jquery.mousehover'); </script>
Example
Insert the text ">>" before the list item, which the mouse pointer is hovering above, and remove the text, as soon as the mouse pointer leaves the list item:
<ul> <li>Apple</li> <li>Orange</li> </ul> <script> $('li').mousehover( function () { $(this).prepend($('<span>>> </span>')); }, function () { $(this).find('span:first').remove(); } ); </script>
Installation
Make sure that you have NodeJS >= 6 installed. You can use either npm
or bower
to install this package and its dependencies.
With NPM:
npm install jquery.mousehover
With Bower:
bower install jquery.mousehover
Build
Make sure that you have NodeJS >= 6 installed. Clone the Github repository to a local directory, enter it and install the package dependencies (including the development dependencies) by npm
:
git clone https://github.com/prantlf/jquery.mousehover.git cd jquery.mousehover npm install
Examples and tests will be functional now.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.
First fork this repository and clone your fork locally instead of cloning the original. See the "Build" chapter above for more details about how to clone it and install the build dependencies.
Before you commit, update minified files and source maps, re-generate documentation and check if tests succeed:
npm run build npm test
Commit your changes to a separtate branch, so that you can create a pull request for it:
git checkout -b <branch name> git commit -a git push origin <branch name>
Release History
- 2018-04-27 v1.0.0 Dropped support of Node.js 4
- 2014-04-28 v0.2.1 Fix detection of pointer and touch events in the browser, fix detection of mouse event type
- 2014-04-25 v0.2.0 Add noConflict method, off method for unregistering event handlers and optional event namespacing
- 2014-04-24 v0.1.0 Initial release
License
Copyright (c) 2017-2019 Ferdinand Prantl
Licensed under the MIT license.