JavaScript MouseEvent pageX Property

What You’ll Learn

MouseEvent.pageX is a read-only number: the mouse’s horizontal position relative to the entire document, including scrolled-away content. Learn how it differs from clientX and offsetX, the scroll formula, and five try-it labs.

Introduction

Absolute-positioned pins, annotations on a long page, and document-space hit maps need “where on the page?” That is pageX (horizontal) and pageY (vertical)—coordinates relative to the whole document, not just the visible window.

document.addEventListener("mousemove", (event) => {
  console.log(event.pageX); // pixels from document left (includes scroll)
});

Understanding the Property

MDN: pageX returns the X (horizontal) coordinate (in pixels) at which the mouse was clicked, relative to the left edge of the entire document. This includes any portion of the document not currently visible.

• Instance — read event.pageX in a handler.
• Number — CSS pixels; a floating-point double.
• Document-relative — includes horizontal scroll.
• Read-only — set via constructor options on synthetic events only.

📝 Syntax

const x = mouseEvent.pageX;

Value

A double floating-point number of pixels from the left edge of the document (MDN), regardless of scrolling or viewport positioning. Originally specified as a long integer; CSSOM View redefined it as a double for subpixel precision.

⚖️ pageX vs Other X Coordinates

Mental model: pageX ≈ clientX + window.scrollX. Pair pageX with pageY for a full document point.

Examples Gallery

Examples follow MDN MouseEvent.pageX. Move the mouse and scroll horizontally in the try-it labs to see document vs viewport values.

const box = document.querySelector(".box");
const pageXEl = document.getElementById("x");
const pageYEl = document.getElementById("y");

function updateDisplay(event) {
  pageXEl.innerText = event.pageX;
  pageYEl.innerText = event.pageY;
}

box.addEventListener("mousemove", updateDisplay);
box.addEventListener("mouseenter", updateDisplay);
box.addEventListener("mouseleave", updateDisplay);

pageX: 248
pageY: 162

// Wide page + horizontal scroll — click near the left of the *window*
document.addEventListener("click", (e) => {
  console.log("clientX:", e.clientX);
  console.log("scrollX:", window.scrollX);
  console.log("pageX:", e.pageX);
  // Often: pageX ≈ clientX + scrollX
  // Example: scrollX 200 + clientX 100 → pageX 300
});

clientX: 100
scrollX: 200
pageX: 300

const event = new MouseEvent("click", {
  pageX: 320,
  pageY: 80,
  bubbles: true
});

console.log(event.pageX); // 320
console.log(event.pageY); // 80

320
80

box.addEventListener("click", (e) => {
  console.log({
    pageX: e.pageX,     // document
    clientX: e.clientX, // viewport
    offsetX: e.offsetX, // target padding edge
    scrollX: window.scrollX
  });
});

{
  pageX: 280,
  clientX: 280,
  offsetX: 40,
  scrollX: 0
}

const pin = document.querySelector("#pin");

document.addEventListener("click", (e) => {
  // pin { position: absolute } on the document/body
  pin.style.left = `${e.pageX}px`;
  pin.style.top = `${e.pageY}px`;
});

Pin jumps to the click using pageX / pageY (document coordinates).

🚀 Common Use Cases

• Absolute markers and annotations on scrolled pages.
• Document-space hit maps and click heatmaps.
• Teaching the difference between viewport and document coordinates.
• Synthetic events in tests with known pageX / pageY.
• Layouts that use position: absolute in document space.

🔧 How It Works

📝 Notes

• Baseline Widely available (MDN, since July 2015).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Includes any portion of the document not currently visible (horizontal scroll).
• Value type is a floating-point double in modern engines (CSSOM View).
• Related: offsetY, clientX, offsetX, MouseEvent(), Window, JavaScript hub.

💡 Best Practices