@react-hook/mouse-position

useMousePosition()

npm i @react-hook/mouse-position

A React hook for tracking the position, hover, and "down" state of the mouse as it interacts with an element. This hook provides interoperability between touch and desktop devices and will treat ontouch events the same as onmouse ones. Additionally, this hook is throttled to 30fps by default using a useThrottle() hook, though the precise frame rate is configurable.

Quick Start

import useMousePosition from '@react-hook/mouse-position'

const Component = (props) => {
  const [mousePosition, ref] = useMousePosition(
    0, // enterDelay
    0, // leaveDelay
    30 // fps
  )

  return (
    // You must provide the ref to the element you're tracking the
    // mouse position of
    <div ref={ref}>
      Hover me and see where I am relative to the element:
      <br />
      x: ${mousePosition.x}
      y: ${mousePosition.y}
    </div>
  )
}

API

useMousePosition(enterDelay?, leaveDelay?, fps?)

A hook for tracking the mouse position in an element with interoperability between touch devices and mouse devices.

Arguments

Argument	Type	Default	Description
enterDelay	number	0	The time in ms to wait after an initial action before setting the latest mousemove events to state
leaveDelay	number	0	The time in ms to wait after a final action before setting the latest mouseleave events to state
fps	number	30	The rate in frames-per-second that the mouse position should update

Returns [state: MousePosition, ref: React.Dispatch<React.SetStateAction<HTMLElement | null>>]

Variable	Type	Description
state	MousePosition	The mouse position data for the ref'd element
ref	`React.Dispatch<React.SetStateAction<HTMLElement	null>>`

MousePosition

Key	Type	Default	Description
x	number	null	Mouse position relative to the left edge of the element, null if mouse is not over the element
y	number	null	Mouse position relative to the top edge of the element, null if mouse is not over the element
pageX	number	null	Mouse position relative to the left edge of the document, null if mouse is not over the element
pageY	number	null	Mouse position relative to the top edge of the document, null if mouse is not over the element
clientX	number	null	Mouse position relative to the left edge of the client, null if mouse is not over the element
clientY	number	null	Mouse position relative to the top edge of the client, null if mouse is not over the element
screenX	number	null	Mouse position relative to the left edge of the screen, null if mouse is not over the element
screenY	number	null	Mouse position relative to the top edge of the screen, null if mouse is not over the element
elementWidth	number	null	DOMRect.width of the element, null if mouse is not over the element
elementHeight	number	null	DOMRect.height of the element, null if mouse is not over the element
isOver	boolean	false	true if the mouse is currently hovering over the element
isDown	boolean	false	true if the mouse is currently hovering over the element AND is down
isTouch	boolean	false	true if the the last event was triggered by a touch event

LICENSE

MIT