use-mouse-leave

useMouseLeave

React hook to reliably run an effect on mouseleave

But why?

mouseleave is about as reliable as rain in the Sahara.

A guy even went so far as using jQuery inside React to have a resemblance of predictability. Imagine that.

Introducing, useMouseLeave.

useMouseLeave is the easiest way to fire effects reliably when the mouse leaves (mouseleave is the name of the native event) an element. Also similar to mouseout, but there probably isn't a need for a useMouseOut hook.

How to use it

Installation

npm install use-mouse-leave
# or
yarn add use-mouse-leave
# or
pnpm add use-mouse-leave
# or
bun add use-mouse-leave

Usage

At the top of your file:

import useMouseLeave from 'use-mouse-leave';

Then in your component function:

[...]

const [mouseLeft, ref] = useMouseLeave();

useEffect(() => {
  if (mouseLeft) {
    // The mouse has just left our element, time to
    // run whatever it was we wanted to run on mouseleave:
    // ...
  }
}, [mouseLeft]);

[...]

return (
  <div ref={ref}>
    ...
  </div>
);

Accessing the inner ref

For some reasons, you might want to access the inner ref.

For example, let's imagine you have a calendar and want to show a popup with more informations when hovering an event.

<EventPopupWrapper target={the event being hovered}>
  <Calendar>
    ...dozens of nested components
         <Event />
  </Calendar>
</PopupWrapper>

You would need to be able to get the event's dom node, to attach the Popup to it.

useMouseLeave exposes its internal ref for you to play with as the third parameter of the returned tuple.

[...]

const [
  mouseLeft,
  setRef, // the callback ref to put on the div
  innerRef, // the internal ref that directly points on the dom node
] = useMouseLeave();

useEffect(() => {
  if (mouseLeft) { ... }
}, [mouseLeft]);

[...]

return (
  <div
    ref={setRef}
    onMouseEnter={() => {
      // innerRef.current => <div ....>
      // you can now use innerRef.current to anchor the popup to this div
    }}
  >
    ...
  </div>
);

Demo

There's also a local demo in this repo's demo folder, useful for testing changes to the hook itself. Clone the repo, npm install, then npm run demo.

How it works

The hook attaches a mouseenter listener (which is reliable) to our element. This listener in turn attaches a mousemove listener to the window object (throttled to 50ms for extra bonus sparkly performance ), and constantly checks whether the pointer is still within the element's box or not. Then removes the window listener when mouseleave is detected, to save resources. That's it.

Please note

The hook treats the pointer as "inside" whenever it's over a DOM descendant of the tracked element, even one positioned relatively, absolutely or fixedly (or transformed) outside the element's own box -- matching how the browser's native mouseenter/mouseleave see it. Only when the pointer lands on something outside that subtree does it fall back to checking the coordinates against getBoundingClientRect(), which is how it also catches the pointer leaving through a gap the box doesn't cover (e.g. a margin).

Content rendered through ReactDOM.createPortal (a tooltip or dropdown mounted onto document.body, say) is a logical child in React's tree, but not an actual DOM descendant of the tracked element -- so the pointer moving onto it falls through to the geometric check above, same as before this was added.

Tests

One day I'll write fancy Cypress tests (probably something like this), for the moment just know that I've personally, tirelessly and manually stress-tested it using the above sandbox on Chrome, Firefox, Safari and Edge. Do test it in your own project though: mouse events are weird.

Credits

Heavily inspired by @mrdanimal's implementation using lifecycle methods.