jQuery event.pageY

What You’ll Learn

event.pageY is a Number property with the pointer’s vertical position relative to the document’s top edge — scroll included. This tutorial covers the official mousemove demo, pairing with pageX, comparing with clientY, click pins, vertical drag, and scroll-aware positioning.

Introduction

When the user moves or clicks the mouse, you often need to know where the pointer was. jQuery forwards coordinate properties from the browser on its event object — including event.pageY for vertical document position.

Unlike viewport coordinates (clientY), pageY counts pixels from the top edge of the full document, so it stays consistent when the page is scrolled. jQuery has exposed it since version 1.0.4.

Understanding event.pageY

This property answers one question: how far down is the pointer from the document’s top edge?

• Origin — top edge of the document (not the viewport, not the clicked element).
• Includes scroll — vertical scroll offset is included in the value.
• Read-only — a Number in pixels; not a method.
• Pair with pageX — use both for full document coordinates.

📝 Syntax

Official jQuery API form (since 1.0.4):

event.pageY

// typical pattern:
$( document ).on( "mousemove", function ( event ) {
  console.log( "X:", event.pageX, "Y:", event.pageY );
});

Parameters

• None — pageY is a property, not a function.

Return value

• Number — vertical mouse position in pixels relative to the top edge of the document.

Official jQuery API example

$( document ).on( "mousemove", function ( event ) {
  $( "#log" ).text( "pageX: " + event.pageX + ", pageY: " + event.pageY );
});

Examples Gallery

Example 1 follows the official jQuery mousemove demo. Examples 2–5 cover click pins, scroll comparison, drag tracking, and coordinate readouts.

$( document ).on( "mousemove", function ( event ) {
  $( "#log" ).text( "pageX: " + event.pageX + ", pageY: " + event.pageY );
});

#log updates continuously:
pageX: 142, pageY: 388
(values change as you move the mouse)

$( "#canvas" ).on( "click", function ( event ) {
  $( "#pin" ).css({
    left: event.pageX + "px",
    top: event.pageY + "px"
  });
  $( "#coords" ).text( "Pinned at pageY: " + event.pageY );
});

Click anywhere → pin moves to (pageX, pageY)
#coords shows "Pinned at pageY: …"

$( document ).on( "click", function ( event ) {
  $( "#compare" ).html(
    "pageY: " + event.pageY + " (document)
" +
    "clientY: " + event.clientY + " (viewport)"
  );
});

Scroll the page down, click same visual spot:
pageY stays document-consistent; clientY is viewport-relative

var startY, startTop;

$( "#box" ).on( "mousedown", function ( event ) {
  startY = event.pageY;
  startTop = parseInt( $( this ).css( "top" ), 10 ) || 0;
  $( document ).on( "mousemove.drag", onDrag );
});

function onDrag( event ) {
  $( "#box" ).css( "top", startTop + ( event.pageY - startY ) );
}

Drag box vertically — top updates by (pageY - startY)
Works correctly even if page is scrolled

$( "#chart" ).on( "mousemove", function ( event ) {
  $( "#hud" )
    .text( "pageY: " + Math.round( event.pageY ) )
    .css({ left: event.pageX + 12, top: event.pageY + 12 })
    .show();
});

$( "#chart" ).on( "mouseleave", function () {
  $( "#hud" ).hide();
});

HUD follows cursor showing rounded pageY
Hidden when mouse leaves #chart

🚀 Common Use Cases

• Coordinate display — show pointer X/Y in debugging HUDs.
• Image annotation — place pins at click pageX / pageY.
• Drag and drop — compute movement deltas with page coordinates.
• Drawing apps — line tools using document-space points.
• Heatmaps — log click positions for analytics.
• Scroll depth — map pageY to how far the user has read down a page.

📝 Notes

• Available since jQuery 1.0.4 — returns a Number (pixels).
• Read-only property on mouse events.
• Relative to the document top edge, not the clicked element.
• Always pair with pageX for 2D document coordinates.
• Use clientY for fixed viewport overlays; offsetY for local element coords.
• jQuery normalizes coordinates consistently across supported browsers.

💡 Best Practices