How to Track Mouse Position in JavaScript

Track pointer movement by registering a callback for the browser’s mousemove event. The callback receives a MouseEvent; read its coordinate properties from that event rather than keeping separate pointer state. The event fires as the pointer moves over the window, so the handler can inspect a fresh position on each movement.

Listen for mouse movement with the mousemove event

A listener has an event type and a callback. In the browser example below, window.addEventListener registers handleMouseMove for mousemove, and the callback reads pageX, pageY, clientX, and clientY. The property names are case-sensitive. The mousemove event reports movement; it does not fire just because the page is loaded or because the pointer is stationary.

The small runnable example shows how the callback formats the event values. Its plain object is sample input for illustrating the property names; use a real browser MouseEvent in an interactive page.

Run this example:

function handleMouseMove(event) {
  console.log(
    `page: (${event.pageX}, ${event.pageY}); client: (${event.clientX}, ${event.clientY})`
  );
}

handleMouseMove({ pageX: 120, pageY: 240, clientX: 120, clientY: 240 });

For the browser interaction, use this self-contained page. Its tall content makes the document scrollable, and the handler logs both coordinate pairs whenever the pointer moves over the page.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Mouse coordinates</title>
  <style>
    body { min-height: 1600px; font: 16px sans-serif; }
    main { padding: 2rem; }
  </style>
</head>
<body>
  <main>
    <h1>Move the pointer, then scroll</h1>
    <p>Open the browser developer console to compare the coordinate pairs.</p>
  </main>
  <script>
    window.addEventListener('mousemove', (event) => {
      console.log(
        `page: (${event.pageX}, ${event.pageY}); client: (${event.clientX}, ${event.clientY})`
      );
    });
  </script>
</body>
</html>

Choose between page and viewport coordinates

pageX and pageY measure the pointer from the top-left of the document. They include the document’s scroll offset, so they are useful when a position must stay tied to content as the reader scrolls. For example, use page coordinates when recording where a point lies in a long document.

clientX and clientY measure from the top-left of the visible viewport. Scrolling does not change that origin. Use these values when positioning or comparing something within the currently visible browser area, such as a custom cursor marker or a viewport overlay.

These pairs describe different coordinate spaces, so use one pair consistently for a calculation. Mixing a page coordinate with a viewport coordinate can shift a result by the scroll offset. Making an element follow the pointer also needs additional mouse events and element-positioning logic; reading coordinates alone does not move an element.

Compare pageX and clientX while scrolling

Before scrolling, the document origin and viewport origin coincide, so the horizontal values pageX and clientX match, as do pageY and clientY. Move the pointer and inspect the console for both pairs. The first supplied view is the planned before-scroll console view.

After scrolling down, the horizontal values generally remain aligned, while the vertical pageY includes the distance scrolled and clientY remains measured from the viewport’s top edge. The difference between the vertical values corresponds to the current scroll offset. The second supplied view is the planned after-scroll console view.

Choose clientX and clientY for locations relative to what is visible now. Choose pageX and pageY for locations relative to the document, including its scrolled content. For the broader set of browser mouse events, see the MDN Mouse Events reference.