useMouse

About

useMouse subscribes to document mousemove events and returns coordinate fields from the latest native event. It is global document tracking, not tracking relative to a supplied element.

Example

import { useMouse } from "rooks";

export default function PointerPosition() {
  const { clientX, clientY, pageX, pageY } = useMouse();

  return (
    <dl>
      <dt>Viewport</dt>
      <dd>
        {clientX ?? "unknown"}, {clientY ?? "unknown"}
      </dd>
      <dt>Page</dt>
      <dd>
        {pageX ?? "unknown"}, {pageY ?? "unknown"}
      </dd>
    </dl>
  );
}

Parameters

This hook has no parameters.

Return value

The returned object contains nullable clientX, clientY, movementX, movementY, offsetX, offsetY, pageX, pageY, screenX, screenY, x, and y. The x and y fields are aliases of screenX and screenY in this implementation. offsetX and offsetY remain relative to the native event target.

Behavior and lifecycle

Before the first event, every field is null. Each document mousemove replaces the snapshot and causes subscribed components to render. There is no throttling. The native listener is removed on unmount, and separate hook instances keep separate snapshots.

Compatibility and accessibility

The server snapshot contains only null values; the browser fills it after a mouse event. Touch, pen, and keyboard input do not update this hook. Do not make an action or essential status depend only on mouse location.

Related

• useMouseMoveDelta returns per-event movement and velocity.