@react-hook/mouse-position

A React hook for tracking the position, hover, and down state of the mouse as it interacts with an element with interop between touch and mouse devices.

Usage no npm install needed!

<script type="module">
  import reactHookMousePosition from 'https://cdn.skypack.dev/@react-hook/mouse-position';
</script>

README


useMouse()

Bundlephobia Types Build status NPM Version MIT License

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

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

LICENSE

MIT