react-hover-observer

    2.1.1 • Public • Published

    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

    CircleCI Coverage Status npm License

    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

    Install

    npm i react-hover-observer

    DownloadsWeekly Downloads

    5,606

    Version

    2.1.1

    License

    MIT

    Unpacked Size

    33.7 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar