react-hover-observer

Optionally observe mouseenter, mouseleave, mouseover, and mouseout events.

Supports delayed hover and hover-off, which can help reduce unintentional triggering.

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.

GitHub