@react-hook/mouse-position NPM

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

Check out the example on CodeSandbox

import * as React from 'react'
import useMouse from '@react-hook/mouse-position'

const Component = (props) => {
  const ref = React.useRef(null)
  const mouse = useMouse(ref, {
    enterDelay: 100,
    leaveDelay: 100,
  })

  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: ${mouse.x}
      y: ${mouse.y}
    </div>
  )
}

API

useMouse(target, options?)

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

Arguments

Argument	Type	Required?	Description
target	React.RefObject<T> \| T \| null	Yes	The React ref, `window`, or HTML element to add the event listener to
options	`UseMouseOptions`	No	Configuration options. See `UseMouseOptions` below

Returns `MousePosition`

The mouse position data for the target element. See MousePosition below.

UseMouseOptions

Property	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

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