JavaScript MouseEvent pageY Property

What You’ll Learn

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

Introduction

Absolute pins on a tall article, annotations down a long page, and document-space hit maps need “how far from the top of the page?” That is pageY (vertical), paired with pageX (horizontal)—coordinates relative to the whole document.

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

Understanding the Property

MDN: pageY returns the Y (vertical) coordinate (in pixels) at which the mouse was clicked, relative to the top edge of the entire document. This includes any portion of the document not currently visible. MDN also points to pageX for the fuller coordinate-system explanation.

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

📝 Syntax

const y = mouseEvent.pageY;

Value

A double floating-point value in pixels (MDN) from the top edge of the document, regardless of scrolling or viewport positioning.

⚖️ pageY vs Other Y Coordinates

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

Examples Gallery

Examples follow MDN MouseEvent.pageY (and the fuller coordinate notes on pageX). Move the mouse and scroll vertically in the try-it labs.

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

// Tall page + vertical scroll — click near the top of the *window*
document.addEventListener("click", (e) => {
  console.log("clientY:", e.clientY);
  console.log("scrollY:", window.scrollY);
  console.log("pageY:", e.pageY);
  // Often: pageY ≈ clientY + scrollY
  // Example: scrollY 200 + clientY 100 → pageY 300
});

clientY: 100
scrollY: 200
pageY: 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({
    pageY: e.pageY,     // document
    clientY: e.clientY, // viewport
    offsetY: e.offsetY, // target padding edge
    scrollY: window.scrollY
  });
});

{
  pageY: 220,
  clientY: 220,
  offsetY: 40,
  scrollY: 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 tall 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 (vertical scroll).
• Value type is a floating-point double (MDN).
• Related: pageX, clientY, offsetY, MouseEvent(), Window, JavaScript hub.

💡 Best Practices