JavaScript MouseEvent clientY Property

What You’ll Learn

MouseEvent.clientY is a read-only number: the mouse’s vertical position inside the viewport. Learn how it differs from pageY and screenY, why vertical scroll does not change the top-edge rule, how it pairs with clientX, and five try-it labs.

Introduction

Together with clientX, clientY answers “how far down is the pointer in the window?” Zero is the top of the visible viewport—not the top of a long scrolled document.

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

Understanding the Property

MDN: clientY provides the vertical coordinate within the application’s viewport at which the event occurred (as opposed to the coordinate within the page). Clicking the top edge of the viewport always yields clientY of 0, even if the page is scrolled vertically.

• Instance — read event.clientY in a handler.
• Number — CSS pixels; often a floating-point double.
• Viewport-relative — not document scroll, not the OS screen.
• Read-only — set via constructor options on synthetic events only.

📝 Syntax

const y = mouseEvent.clientY;

Value

A number (double) in CSS pixels from the top edge of the viewport.

⚖️ clientY vs Other Y Coordinates

Pair clientY with clientX for a full viewport point. For document-relative placement on a tall page, prefer pageX / pageY.

Examples Gallery

Examples follow MDN MouseEvent.clientY. Move the mouse and compare vertical coordinate systems in the try-it labs.

const screenLog = document.querySelector("#screen-log");

document.addEventListener("mousemove", (e) => {
  screenLog.innerText = `
    Screen X/Y: ${e.screenX}, ${e.screenY}
    Client X/Y: ${e.clientX}, ${e.clientY}`;
});

Screen X/Y: 640, 400
Client X/Y: 220, 160

// Tall page + vertical scroll — click near the top of the *window*
document.addEventListener("click", (e) => {
  console.log("clientY:", e.clientY);
  console.log("pageY:", e.pageY);
  // Near viewport top: clientY ≈ 0 even if pageY is large after scrolling
});

clientY: 18
pageY: 818

const event = new MouseEvent("click", {
  clientX: 120,
  clientY: 40,
  bubbles: true
});

console.log(event.clientX); // 120
console.log(event.clientY); // 40

120
40

document.addEventListener("click", (e) => {
  console.log({
    clientY: e.clientY,
    pageY: e.pageY,
    scrollY: window.scrollY
  });
  // Often: pageY ≈ clientY + scrollY
});

{
  clientY: 150,
  pageY: 150,
  scrollY: 0
}

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

document.addEventListener("mousemove", (e) => {
  tip.style.left = `${e.clientX + 12}px`;
  tip.style.top = `${e.clientY + 12}px`;
  tip.textContent = `${e.clientX}, ${e.clientY}`;
});

Tip element follows the pointer using position: fixed and clientX/clientY.

🚀 Common Use Cases

• Floating tooltips and custom cursors that track the pointer in the window.
• Measuring how far down the pointer is for viewport-fixed chrome.
• Logging vertical position while teaching coordinate systems.
• Synthetic events in tests with known clientX / clientY.
• Choosing between viewport (client*) and document (page*) layouts.

🔧 How It Works

📝 Notes

• Baseline Widely available (MDN, since July 2015).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Top edge of the viewport ⇒ clientY === 0, regardless of vertical scroll.
• Related: clientX, ctrlKey, buttons, MouseEvent(), Window, JavaScript hub.

💡 Best Practices