Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
106 lines (78 sloc) 3.04 KB

useMouseEvents

Returns an object of handler setters to handle the mouse events. It accepts a DOM ref representing the events target (where attach the events to).

If a target is not provided the events will be globally attached to the document object.

Returned handler setters: onMouseDown, onMouseEnter, onMouseLeave, onMouseMove, onMouseOut, onMouseOver, onMouseUp;

Please note: the returned handler setters should invoked immediately in the function component's body, do not try to call this functions asynchronously.

Why? πŸ’‘

  • takes care of adding the mouse events listeners globally or to the defined target
  • takes care of cleaning the listener when the component will unmount
  • allow to perform abstractions on mouse related events

Basic Usage:

Provide a DOM ref as first parameter to useMouseEvents

import { useRef, useState } from 'react';
import { useMouseEvents } from 'beautiful-react-hooks'; 

const MyComponent = () => {
  const [coordinates, setCoordinates] = useState();
  const ref = useRef();
  const { onMouseMove, onMouseLeave } = useMouseEvents(ref);

  onMouseMove((event) => {
    const nextCoords = [event.clientX, event.clientY];
    setCoordinates(nextCoords);
  });

  onMouseLeave(() => {
    setCoordinates(undefined);
  });

  return (
    <DisplayDemo>
      <div ref={ref}>
        Move mouse over me to get its current coordinates.
        {coordinates && <p>Coordinates x:{coordinates[0]} y:{coordinates[1]}</p>}
      </div>
    </DisplayDemo>
  );
};

<MyComponent />

Global events

Avoid providing any argument to useMouseEvents

import { useState } from 'react';
import { useMouseEvents } from 'beautiful-react-hooks'; 

const MyComponent = () => {
  const [coordinates, setCoordinates] = useState([0, 0]);
  const { onMouseMove } = useMouseEvents();

  onMouseMove((event) => {
    const nextCoords = [event.clientX, event.clientY];
    setCoordinates(nextCoords);
  });

  return (
    <DisplayDemo>
      The current mouse coordinates are:
      <p>x:{coordinates[0]} y:{coordinates[1]}</p>
    </DisplayDemo>
  );
};

<MyComponent />

Mastering the hook

βœ… When to use

  • If in need to abstract some mouse related logic into a custom hooks

πŸ›‘ What not to do

  • You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in your code.
  • Absolutely avoid using useMouseEvents handler setters to replace the standard mouse handler props.
  • useMouseEvents is meant to be used to abstract more complex hooks that need to control the mouse, for example: a drag n drop hook.
  • Using useMouseEvents handlers instead of the classic props approach it's just as bad as it sounds since you'll lose the React SyntheticEvent performance boost.
  • If you were doing something like the following, please keep doing it:
const MyComponent = (props) => {
  const { mouseDownHandler } = props;
    
  return (
    <div onMouseDown={mouseDownHandler} />
  );
};
You can’t perform that action at this time.