jQuery event.pageY Property

Beginner
6 min read
Updated: Oct 2026
5 examples
Live preview
jQuery event.pageY property — mouse vertical position relative to the document top edge
Definition

What Is event.pageY?

event.pageY is a Number on the jQuery event object. It is the mouse pointer’s vertical position in pixels relative to the top edge of the document (scroll included). Added in jQuery 1.0.4. Pair it with event.pageX for a full document (x, y) point.

Remember
event.pageY   // Number — px from document top (read-only)

$(document).on("mousemove", function (event) {
  // pageX: horizontal · pageY: vertical
  console.log(event.pageX, event.pageY);
});

pageY   → document coordinates (includes scroll)
clientY → viewport coordinates (visible window)
offsetY → relative to the event target element
NeedUse
Document Yevent.pageY
Document Xevent.pageX
Track the pointer.on("mousemove", …)
Click position.on("click", …) + pageY
Viewport Yevent.clientY (native / originalEvent)
Approach

How to Use event.pageY

Bind a mouse event, then read pageY (and usually pageX) inside the handler.

  1. Choose a mouse event (mousemove, click, mousedown, …).
  2. Bind with .on("mousemove", handler) (or click / mousedown).
  3. Inside the handler, read event.pageY — pixels from the document’s top edge.
  4. For a full point, also read event.pageX.
  5. Use document coords for pins, drag, and scroll-aware UI — not viewport-only math.
PieceRequired?Role
Mouse eventYesProvides pointer coordinates
event.pageY—Vertical px from document top
event.pageXOptionalHorizontal px from document left
HandlerYesReads and uses the values

Pseudocode

Pseudocode
element.on("mousemove" | "click" | …, handler)

when mouse event fires:
    event.pageX = distance from document left (px)
    event.pageY = distance from document top  (px)
    // includes scroll — not just the visible viewport
    call handler(event)

// Rough relation:
// pageY ≈ clientY + window.scrollY
Reference

Cheat Sheet

Keep these facts handy while reading pointer coordinates.

TopicDetail
TypeNumber property (not a method)
SincejQuery 1.0.4
OriginDocument top edge
UnitCSS pixels
Official demomousemove → log pageX + pageY
vs clientYDocument (+ scroll) vs viewport
vs offsetYDocument vs target element
Mutates?No — read-only
Try it

Live Preview

Move the pointer over the pad to see pageY and pageX — same idea as the official jQuery API demo.

Bound with .on("mousemove") — move over the pad to update coordinates.

Result
Move your mouse over the pad…
Code

jQuery Examples

Short, copy-ready snippets. Open DevTools, or use Try It Yourself for a live editor.

Example 1 — Official Demo: Log pageX / pageY

On mousemove, show both document coordinates (official idea).

jQuery
$(document).on("mousemove", function (event) {
  $("#out").text(
    "pageX: " + event.pageX + ", pageY: " + event.pageY
  );
});
Try It Yourself

How It Works

  1. Bind. mousemove on document catches moves anywhere on the page.
  2. Read X. event.pageX is distance from the document’s left edge.
  3. Read Y. event.pageY is distance from the document’s top edge.
  4. Update. Each move rewrites the log — same as the official demo.

Example 2 — Click Coordinates

Capture where the user clicked using pageY (and pageX).

jQuery
$(document).on("click", function (event) {
  $("#out").text(
    "Clicked at pageX: " + event.pageX +
    ", pageY: " + event.pageY
  );
});
Try It Yourself

How It Works

  1. Bind click. One handler for any click on the page.
  2. Read. pageX / pageY are the click point in document space.
  3. Show. Write the pair into #out.
  4. Use case. Same numbers you would use to place a pin or marker.

Example 3 — pageY vs clientY

Document coordinates include scroll; viewport coordinates do not.

jQuery
$(document).on("click", function (event) {
  $("#out").text(
    "pageY: " + event.pageY + " (document)\n" +
    "clientY: " + event.clientY + " (viewport)\n" +
    "scrollY: " + window.scrollY
  );
});
Try It Yourself

How It Works

  1. pageY. Measured from the document’s top edge.
  2. clientY. Measured from the viewport’s top edge.
  3. Scroll. When scrollY > 0, pageY is larger than clientY.
  4. Rule. Need layout on the full page? Prefer pageY.

Example 4 — Track pageY Delta

Measure how far the pointer moved vertically since mousedown (drag idea).

jQuery
var startY = 0;

$("#box").on("mousedown", function (event) {
  startY = event.pageY;
  $("#out").text("Start pageY: " + startY);
  $(document)
    .on("mousemove.drag", function (event) {
      var dy = event.pageY - startY;
      $("#out").text("Delta Y: " + dy + " px");
    })
    .on("mouseup.drag", function () {
      $(document).off(".drag");
      $("#out").append("\nReleased.");
    });
});
Try It Yourself

How It Works

  1. Store. On mousedown, save the starting pageY.
  2. Move. On mousemove, subtract start from current pageY.
  3. Delta. Positive = moved down; negative = moved up.
  4. Cleanup. On mouseup, remove the temporary .drag handlers.

Example 5 — Pair pageY with pageX

Hover a region and report both document coordinates together.

jQuery
$("#area").on("mousemove", function (event) {
  $("#out").text(
    "Inside area — pageX: " + event.pageX +
    ", pageY: " + event.pageY
  );
}).on("mouseleave", function () {
  $("#out").text("Left the area.");
});
Try It Yourself

How It Works

  1. Scope. Bind on #area so only moves inside that element count.
  2. Both axes. Log pageX and pageY as one document point.
  3. Leave. mouseleave clears or resets the readout.
  4. Pattern. Useful for charts, maps, and hover HUDs.

Edge Cases & Pitfalls

Watch for these when using pageY in real UI.

scroll

Do not mix pageY with viewport math

Positioning an element with position: fixed needs viewport coords (clientY). Document layout / absolute pins need pageY.

events

Only mouse (pointer) events

Keyboard events do not give a meaningful pageY. Bind mousemove, click, mousedown, and related mouse events.

freq

mousemove fires very often

Keep handlers light. Heavy DOM work on every move can stutter — throttle or only update what changed.

readonly

You cannot assign event.pageY

It is read-only. Copy the value into your own variable or CSS if you need to reuse it.

Compatibility

Browser Support

event.pageY is a jQuery event-object property (since 1.0.4). The underlying mouse coordinates are standard in all modern browsers. Works wherever your loaded jQuery version runs.

✓ Stable · jQuery 1.0.4+

event.pageY

Supported wherever jQuery 1.0.4+ is loaded. Prefer jQuery 3.x with .on("mousemove") / .on("click") for modern code.

100% jQuery support
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
event.pageY 1.0.4+

Bottom line: Safe for production. Use pageY for document coordinates; pair with pageX; use clientY only when you need viewport space.

Analysis

Performance Notes

ApproachCostBest for
.on("click", …) + pageYCheapOne-shot click positions
.on("mousemove", …)High frequencyLive tracking — keep work tiny
Delegated document mousemoveFineGlobal cursor HUD / tools
Heavy layout in mousemoveCan stutterThrottle or update only changed fields

Reading pageY itself is free. The cost is how often you run the handler — especially on mousemove.

Remember

Key Takeaways

  • Role: vertical mouse position from the document’s top edge.
  • Pair: use pageX for the horizontal axis.
  • vs clientY: pageY includes scroll; clientY is viewport-only.
  • Keep light: mousemove handlers should stay short.

One line: event.pageY is “how far from the document’s top edge is the pointer?”

Frequently Asked Questions

event.pageY is a Number on the jQuery event object. It is the mouse pointer’s vertical position in pixels relative to the top edge of the document — including any vertical scroll. Available since jQuery 1.0.4 on mouse events such as mousemove, click, and mousedown.
clientY is relative to the browser viewport (visible window). pageY includes document scroll — roughly pageY ≈ clientY + window.scrollY. Use pageY for document-wide coordinates; clientY for viewport-fixed UI.
pageY is vertical (from the document’s top edge). pageX is horizontal (from the document’s left edge). Together they form a (x, y) point in document space — the official jQuery demo logs both on mousemove.
Mouse events expose pageY — mousemove, mouseenter, mouseleave, mouseover, mouseout, mousedown, mouseup, and click. Keyboard events do not carry a meaningful pointer pageY.
No. pageY is read-only — the browser sets it from the pointer when the event fires. Read pageY and apply it to your own variables or element positions.
pageY is relative to the entire document. offsetY is relative to the event target’s padding edge. Use pageY for absolute document positioning; offsetY for clicks inside a specific box.

Next: event.relatedTarget

See the other element involved in mouseover and mouseout events.

event.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)

9 people found this page helpful

jQuery event.pageX Property jQuery event.relatedTarget Property