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.
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.
$(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.
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'
}
});
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);
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);
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'});
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>
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>
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
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.
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>
- 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
Copyright (c) 2017-2019 Ferdinand Prantl
Licensed under the MIT license.