react-hover-observer
A React component that notifies its children of hover interactions.
Optionally observe mouseenter, mouseleave, mouseover, and mouseout events.
Supports delayed hover and hover-off, which can help reduce unintentional triggering.
Status
Demo
Experiment with these editable examples on CodePen.
- Basic Example - See react-hover-observer in action and how child components receive the isHovering prop.
- onMouseOver example - One use case for onMouseOver and onMouseOut is to control hover state when child components are hovered.
- onHoverChanged example - Implement onHoverChanged when a parent component or global store should be notified of hover changes.
- hoverDelayInMs and hoverOffDelayInMs - Implement these props to help reduce unintended hovers.
Related Project
For mouse or touch position monitoring, please consider react-cursor-position.
Installation
npm install --save react-hover-observer
Usage
import ReactHoverObserver from 'react-hover-observer';
export default () => (
<ReactHoverObserver>
<YourChildComponent />
</ReactHoverObserver>
);
Each child component of ReactHoverObserver receives a Boolean prop named isHovering
.
react-hover-observer wraps its children in a div, which is the boundary for triggering hover events.
Optionally implement the function as child component pattern. This is especially useful if your component has an incompatible interface with react-hover-observer.
export default () => (
<ReactHoverObserver>
{({ isHovering }) => (
<YourChildComponent isActive={isHovering} />
)}
</ReactHoverObserver>
);
Props API
className
: String [optional] - A CSS class to be applied to the div rendered by react-hover-observer.
hoverDelayInMs
: Number [optional] - Milliseconds to delay hover trigger. Defaults to zero. See the hoverDelayInMs example for more.
hoverOffDelayInMs
: Number [optional] - Milliseconds to delay hover-off trigger. Defaults to zero.
onHoverChanged
: Function [optional] - Called with named argument isHovering
when isHovering is set or unset. See the onHoverChanged example for more.
shouldDecorateChildren
: Boolean [optional] - Defaults to true. Optionally suppress decoration of child components by setting this prop false.
onMouseEnter
: Function [optional] - Defaults to set isHovering.
onMouseLeave
: Function [optional] - Defaults to unsetting isHovering.
onMouseOver
: Function [optional] - See the onMouseOver example for more.
onMouseOut
: Function [optional]
Each of the previous four observer functions receives a prameter of type Object with the following properties:
-
e
: Object - The browser event object (React synthetic event).
-
setIsHovering
: Function - Call this function to set isHovering
to true.
-
unsetIsHovering
: Function - Call this function to set isHovering
to false.
onMouseOver
and onMouseOut
can be used to control hover state when child components are hovered. See the onMouseOver example for more.
onMouseEnter/onMouseLeave Versus onMouseOver/onMouseOut
onMouseEnter
and onMouseLeave
are not triggered by hover events bubbling up from child elements.
onMouseOver
and onMouseOut
are triggered by hover events bubbling up from child elements.
The behavior is determined by mouse event Web standards.
See the docs at MDN for more.
Support
Please open an issue.
Development
git clone https://github.com/ethanselzer/react-hover-observer.git
cd react-hover-observer
yarn
See available commands:
npm run
Contributing
Please contribute using Github Flow. Create a branch,
add commits, and open a pull request.
License
MIT