useMouse

React sensor hooks that track cursor position

useMouse tracks the mouse cursor position across multiple coordinate systems by listening to mousemove events. It returns an object with screenX/screenY (relative to the screen), clientX/clientY (relative to the viewport), pageX/pageY (relative to the document), and elementX/elementY/elementW/elementH/elementPosX/elementPosY (relative to a target element, if provided). All values update in real time as the cursor moves.

When to Use

• Building custom cursors, tooltips, or context menus that follow the mouse position
• Implementing drag interactions, drawing canvases, or parallax effects
• Tracking mouse position relative to a specific element for hover-based visualizations

Notes

• SSR-safe: Returns all coordinates as 0 during server-side rendering. No mousemove listeners are attached on the server.
• Element-relative coordinates: Pass a ref to a DOM element to also get coordinates relative to that element, including its dimensions and position.
• Related hooks: See also useMousePressed for tracking press state, and useElementByPoint for detecting which element is under the cursor.

Usage

function Demo() {
  const mouse = useMouse();

  return (
    <div>
      <p>
        Client - x: {mouse.clientX}, y: {mouse.clientY}
      </p>
      <p>
        Page - x: {mouse.pageX}, y: {mouse.pageY}
      </p>
      <p>
        Screen - x: {mouse.screenX}, y: {mouse.screenY}
      </p>
    </div>
  );
};

API

useMouse

Returns

UseMouseCursorState: Mouse Position

Arguments

UseMouseCursorState

Type

export interface UseMouseCursorState { screenX: number screenY: number clientX: number clientY: number pageX: number pageY: number elementX: number elementY: number elementH: number elementW: number elementPosX: number elementPosY: number }

BasicTarget

export type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;

TargetValue

type TargetValue<T> = T | undefined | null;

TargetType

type TargetType = HTMLElement | Element | Window | Document | EventTarget;