JavaScript Get Mouse Coordinates

Live Demo: Four Coordinate Systems at Once

Move your mouse over the gridded area below. All four coordinate systems update simultaneously. This is the fastest way to understand the difference between them -- you can literally see screenX stay larger than clientX because it counts from your physical monitor corner, not the browser viewport.

The Basics: mousemove in One Minute

Every mouse coordinate in JavaScript starts with the mousemove event. You attach a listener, read the event object, and you get X and Y values. That is the entire foundation:

document.addEventListener('mousemove', function(e) {
  console.log(e.clientX, e.clientY);
});

The event object e carries a stack of coordinate properties. The four you will actually use are offsetX, clientX, pageX, and screenX (plus their Y counterparts). They all describe the same physical mouse position, but measured from different reference points.

The mistake most tutorials make: they show you clientX and call it a day. But when you build a real drag-and-drop, a canvas drawing tool, or a tooltip positioning system, picking the wrong coordinate property causes subtle, hair-pulling bugs. The demo above exists so you never have to guess again.

offsetX vs clientX vs pageX vs screenX: Which One?

Here is the comparison table that should have been on every tutorial page but was not. Each property measures the same cursor position from a different origin point:

The one that trips people up: pageX includes scroll offset, clientX does not. If your page is 3000px tall and you scroll down 1000px, then pageY will be roughly 1000 more than clientY at the same cursor position. The live demo above proves this -- scroll down and watch the gap.

Rule of thumb: use clientX/clientY for 90% of UI positioning tasks. Reach for offsetX when you only care about the element under the cursor. Use pageX when you need document-anchored coordinates (canvas drawing, absolutely positioned elements). Almost never use screenX in normal web development.

getBoundingClientRect(): The Swiss Army Knife You Need

Here is something tutorials barely cover: the most useful coordinate function in JavaScript is not a mouse event property at all. It is Element.getBoundingClientRect(). It returns the size and position of any element relative to the viewport:

var rect = element.getBoundingClientRect();
// rect.left, rect.top     -- distance from viewport top-left
// rect.right, rect.bottom -- opposite edges
// rect.width, rect.height -- element dimensions
// All values include CSS border but NOT margin

The real power: subtract rect.left from e.clientX to get the mouse position relative to that element, regardless of where it sits on the page. This is how you build reliable click targets, canvas drawing, and drag zones:

element.addEventListener('mousemove', function(e) {
  var rect = this.getBoundingClientRect();
  var localX = e.clientX - rect.left;  // X relative to this element
  var localY = e.clientY - rect.top;   // Y relative to this element
  console.log('Mouse inside element:', localX, localY);
});

CSS Transforms: Where Coordinates Silently Break

This is the section born from real bug reports. If you apply transform: scale() or transform: rotate() to an element, the coordinate properties start lying to you -- and the documentation barely mentions it.

transform: scale() distorts offsetX

When you scale an element to 50%, the browser shrinks the visual size but offsetX reports coordinates in the scaled coordinate space. If your element is 200px wide and scaled to 0.5, moving the mouse to the visual center gives offsetX = 50, not 100. The getBoundingClientRect() approach also returns scaled dimensions.

// WRONG: offsetX under scale() gives scaled coordinates
// If element is scaled to 0.5, offsetX is halved
element.style.transform = 'scale(0.5)';
element.addEventListener('mousemove', function(e) {
  console.log(e.offsetX); // Reports in scaled space
});

// CORRECT: Use getBoundingClientRect for true visual position
element.addEventListener('mousemove', function(e) {
  var rect = element.getBoundingClientRect();
  var visualX = e.clientX - rect.left;
  var visualY = e.clientY - rect.top;
  // To get the unscaled coordinate:
  var scaleX = element.offsetWidth / rect.width;
  var realX = visualX * scaleX;
  console.log('Unscaled X:', realX);
});

SVG elements: offsetX behaves differently

In SVG, offsetX/offsetY may reference the SVG root or the specific child shape depending on browser. The reliable approach is getBoundingClientRect() or createSVGPoint():

// SVG: use createSVGPoint for accurate coordinates
var svg = document.querySelector('svg');
var pt = svg.createSVGPoint();
svg.addEventListener('pointermove', function(e) {
  pt.x = e.clientX;
  pt.y = e.clientY;
  // Convert to SVG user space:
  var svgPoint = pt.matrixTransform(
    svg.getScreenCTM().inverse()
  );
  console.log('SVG coords:', svgPoint.x, svgPoint.y);
});

Pointer Events: Stop Using mousemove Alone

If you are still writing separate handlers for mousemove, touchmove, and touchstart, you are doing three times the work for worse results. Pointer Events unify mouse, touch, and pen into a single API:

// Old way: three event types, three handlers
element.addEventListener('mousemove', handleMouse);
element.addEventListener('touchmove', handleTouch);  // different event shape!
element.addEventListener('touchstart', handleTouchStart);

// Modern way: one event type
element.addEventListener('pointermove', function(e) {
  // Same properties as MouseEvent:
  console.log(e.clientX, e.clientY, e.pointerType);
  // pointerType: 'mouse', 'touch', or 'pen'
});

The key advantage: pointermove fires for mouse, finger, and stylus with the exact same clientX/clientY interface. No more mapping touches[0] to a fake mouse event.

Performance: Throttle vs requestAnimationFrame

A mousemove event can fire over 100 times per second on a fast computer. If your handler does DOM updates, layout calculations, or canvas redraws, you will tank performance. Two solutions: throttling and requestAnimationFrame.

Throttling (limit calls per second)

// Throttle: max one call per 16ms (~60fps)
var lastTime = 0;
element.addEventListener('mousemove', function(e) {
  var now = Date.now();
  if (now - lastTime < 16) return;
  lastTime = now;
  doExpensiveWork(e.clientX, e.clientY);
});

requestAnimationFrame (sync with browser repaint)

// rAF: batch updates to the next frame
var pendingEvent = null;
element.addEventListener('mousemove', function(e) {
  pendingEvent = e;  // Store latest, drop intermediates
});
function update() {
  if (pendingEvent) {
    doExpensiveWork(pendingEvent.clientX, pendingEvent.clientY);
    pendingEvent = null;
  }
  requestAnimationFrame(update);
}
requestAnimationFrame(update);

Which is better? requestAnimationFrame is the superior approach for visual updates because it syncs with the display refresh rate and automatically pauses when the tab is not visible. Throttling is simpler for non-visual tasks like analytics logging. For anything that moves pixels on screen, use rAF.

Measured impact

On a typical page with a canvas redraw in the handler: raw mousemove drops to 12-15fps under heavy mouse movement. Throttled to 60fps: smooth but still does redundant work between frames. With rAF: stays at 60fps with zero wasted renders. The difference is visible in real applications.

Production Code: Drag-and-Drop with Boundary Clamping

Here is the drag-and-drop implementation we wish we had when starting out. It uses pointermove (unified mouse/touch), clamps the element within a container, and cleans up listeners properly:

function makeDraggable(element, container) {
  var isDragging = false;
  var startX, startY, origLeft, origTop;

  element.addEventListener('pointerdown', function(e) {
    isDragging = true;
    startX = e.clientX;
    startY = e.clientY;
    var rect = element.getBoundingClientRect();
    origLeft = rect.left;
    origTop = rect.top;
    element.setPointerCapture(e.pointerId);
    e.preventDefault();
  });

  element.addEventListener('pointermove', function(e) {
    if (!isDragging) return;
    var deltaX = e.clientX - startX;
    var deltaY = e.clientY - startY;
    var newLeft = origLeft + deltaX;
    var newTop = origTop + deltaY;

    // Boundary clamping: keep element inside container
    var cRect = container.getBoundingClientRect();
    var eRect = element.getBoundingClientRect();
    var maxLeft = cRect.right - eRect.width;
    var maxTop = cRect.bottom - eRect.height;
    newLeft = Math.max(cRect.left, Math.min(newLeft, maxLeft));
    newTop = Math.max(cRect.top, Math.min(newTop, maxTop));

    element.style.left = newLeft + 'px';
    element.style.top = newTop + 'px';
  });

  element.addEventListener('pointerup', function(e) {
    isDragging = false;
    element.releasePointerCapture(e.pointerId);
  });
}

Two things make this production-ready: setPointerCapture() ensures the element keeps receiving events even if the cursor leaves it mid-drag, and the boundary clamping uses getBoundingClientRect() to respect actual rendered sizes rather than guessing from CSS values.

Canvas Coordinate Mapping

Drawing on a canvas requires mapping mouse coordinates to canvas pixel space. When the canvas has CSS sizing different from its internal resolution (which it should, for HiDPI displays), the naive approach breaks:

var canvas = document.getElementById('my-canvas');
var ctx = canvas.getContext('2d');

// Set internal resolution for HiDPI
var dpr = window.devicePixelRatio || 1;
var rect = canvas.getBoundingClientRect();
canvas.width = rect.width * dpr;
canvas.height = rect.height * dpr;
ctx.scale(dpr, dpr);

canvas.addEventListener('pointermove', function(e) {
  var rect = canvas.getBoundingClientRect();
  // CSS pixel coordinates (what you draw with):
  var cssX = e.clientX - rect.left;
  var cssY = e.clientY - rect.top;
  // If you need raw canvas pixels:
  var pixelX = cssX * dpr;
  var pixelY = cssY * dpr;
  ctx.fillRect(cssX - 2, cssY - 2, 4, 4); // Draw at cursor
});

The dpr (device pixel ratio) scaling is essential on Retina/HiDPI displays. Without it, your canvas drawing appears blurry and coordinate clicks are slightly off. We cover this in depth in our physical vs logical pixels guide.

FAQ: Common Gotchas