JavaScript MouseEvent pageY Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property
Decorative image with the word PAGEY

Definition

MouseEvent.pageY is a read-only number: the vertical pointer position in CSS pixels from the top edge of the entire document, including content scrolled out of view.

Read the notes below before you rely on this property. Prefer feature detection when support is limited.

Syntax

Use event.pageY. Start with this line.

JavaScript
event.pageY
CallWhat it does
event.pageYPrimary signature.

Built into the browser. Read event.pageY on a MouseEvent — no import required.

Library declarations
JavaScript
event.pageY

Parameters

ParameterDescription
Mouse / pointer eventRequired. Source of pageY
window.scrollYOptional. Explains pageY ≈ clientY + scrollY

Return Value

Return ValueDescription
*The current value of event.pageY.

JavaScript Examples

Example 1 — Log pageX / pageY

Print document coordinates while you move (same pattern as MDN’s pageX demo).

JavaScript
const x = document.getElementById("x");
const y = document.getElementById("y");

function updateDisplay(event) {
  x.textContent = event.pageX;
  y.textContent = event.pageY;
}

document.addEventListener("mousemove", updateDisplay);
Try It Yourself

How It Works

  1. Grab the output nodes. Two elements will show the latest X and Y.
  2. Listen for moves. Each mousemove delivers a fresh MouseEvent.
  3. Read document coords. pageY is relative to the document’s top edge.
  4. Update the UI. Replace the text with the current values.

Example 2 — pageY vs clientY + Scroll

Confirm the usual relationship with window.scrollY.

JavaScript
document.addEventListener("click", (e) => {
  console.log({
    pageY: e.pageY,
    clientY: e.clientY,
    scrollY: window.scrollY,
    sum: e.clientY + window.scrollY
  });
});
Try It Yourself

How It Works

  1. Read three numbers. Document Y, viewport Y, and current vertical scroll.
  2. Add viewport + scroll. clientY + scrollY usually matches pageY.
  3. Scroll the page and click again — pageY grows while clientY can stay similar.
  4. Rule of thumb. Need absolute page position? Prefer pageY over reinventing the math.

Example 3 — pageY vs offsetY

Document space and element-local space answer different questions.

JavaScript
box.addEventListener("click", (e) => {
  console.log({
    pageY: e.pageY,     // whole document
    offsetY: e.offsetY, // inside #box padding edge
    clientY: e.clientY  // viewport
  });
});
Try It Yourself

How It Works

  1. Listen on a box. The click still carries all three Y properties.
  2. Document Y. pageY places the click on the full page.
  3. Local Y. offsetY places the click inside the element.
  4. Choose by job. Markers on a tall scrolled page → pageY; hit-test inside a control → offsetY.
Compatibility

Browser Support

MouseEvent.pageY is Baseline Widely available (MDN: since July 2015). It is not Deprecated, Experimental, or Non-standard.

✓ Baseline · Widely available

MouseEvent.pageY

Document-relative vertical pointer coordinate — includes vertical scroll for absolute page positions.

Universal Widely available
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
pageY Excellent

Bottom line: Safe to use in modern browsers. Pair with pageX for document points; use clientY for viewport-only work and offsetY for element-local hits.

Frequently Asked Questions

It is a read-only number: the vertical mouse position in CSS pixels relative to the top edge of the entire document, including any part of the page that is scrolled out of view.
No. MDN marks MouseEvent.pageY as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
pageY includes vertical scroll. If 200px of the top is scrolled away and you click 100px from the viewport’s top edge, pageY is about 300 — the same idea as pageX for the horizontal axis.
clientY is relative to the viewport and ignores document scroll. pageY is relative to the document and grows when you scroll down. Often: pageY ≈ clientY + window.scrollY.
offsetY is relative to the target element’s top padding edge. pageY is relative to the whole document. Use offsetY for clicks inside a box; use pageY for markers on a tall scrolled page.
A double floating-point value in pixels (MDN). Pair it with pageX for a full document point.

Next: MouseEvent.relatedTarget

Learn the secondary EventTarget used with mouseenter, mouseleave, and focus moves.

relatedTarget tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript MouseEvent pageX Property JavaScript MouseEvent relatedTarget Property