JavaScript MouseEvent layerY Property

What You’ll Learn

MouseEvent.layerY is a non-standard read-only Y coordinate relative to the current “layer.” Learn how positioned elements change its meaning, how it compares to pageY, what to use instead, and five try-it labs.

Introduction

Older browsers exposed layerX / layerY for mouse position relative to a “layer.” In practice: for normal flow content it often behaves like document coordinates; inside an element with CSS positioning (absolute, relative, fixed, …) it is relative to that positioned box.

element.addEventListener("mousedown", (event) => {
  console.log(event.layerY); // non-standard — may be undefined
});

Understanding the Property

MDN: MouseEvent.layerY returns the vertical coordinate of the event relative to the current layer. It takes page scrolling into account and returns a value relative to the whole document unless the event occurs inside a positioned element, where the value is relative to the top-left of that positioned element.

• Instance — read event.layerY in a handler.
• Integer pixels — Y when the mouse event fired (when supported).
• Non-standard — not in any official specification.
• Position-sensitive — meaning changes inside positioned elements.

📝 Syntax

const y = mouseEvent.layerY;

Value

An integer in pixels for the Y coordinate of the pointer when the event fired (if the engine exposes the property).

Safe read with fallback

function getY(event) {
  if (typeof event.layerY === "number") {
    return event.layerY; // legacy / non-standard
  }
  return event.pageY; // standard fallback
}

⚖️ layerY vs Standard Coordinates

Examples Gallery

Examples follow MDN MouseEvent.layerY. Click unpositioned and positioned boxes to see how values diverge from pageY.

document.addEventListener("mousedown", (e) => {
  const supported = typeof e.layerY === "number";
  console.log(supported ? e.layerY : "layerY not available");
});

142
# or: layerY not available

unpositioned.addEventListener("mousedown", (e) => {
  console.log({
    layerY: e.layerY,
    pageY: e.pageY
  });
});

{
  layerY: 220,
  pageY: 220
}

positioned.addEventListener("mousedown", (e) => {
  console.log({
    layerY: e.layerY, // often relative to positioned box
    pageY: e.pageY,   // still absolute in the document
    offsetY: e.offsetY
  });
});

{
  layerY: 12,
  pageY: 640,
  offsetY: 12
}

function showCoords(evt) {
  const form = document.forms.form_coords;
  form.parentId.value = evt.target.parentNode.id || "(none)";
  form.pageXCoords.value = evt.pageX;
  form.pageYCoords.value = evt.pageY;
  form.layerXCoords.value = evt.layerX;
  form.layerYCoords.value = evt.layerY;
}

window.addEventListener("mousedown", showCoords);

Form fields update with pageX/pageY and layerX/layerY on each mousedown.

function pointerY(event, mode = "page") {
  if (mode === "client") return event.clientY;
  if (mode === "offset") return event.offsetY;
  return event.pageY; // default: document
}

document.addEventListener("mousedown", (e) => {
  console.log({
    page: pointerY(e, "page"),
    client: pointerY(e, "client"),
    offset: pointerY(e, "offset")
  });
});

{
  page: 310,
  client: 310,
  offset: 24
}

🚀 Common Use Cases

• Reading legacy code that still inspects layerX / layerY.
• Comparing positioned vs document coordinates while learning mouse APIs.
• Migrating old handlers to offsetY, pageY, or clientY.
• Feature-detecting before touching non-standard properties.
• Teaching why non-standard APIs are risky in production.

🔧 How It Works

📝 Notes

• MDN: Non-standard; not part of any specification.
• Not Deprecated or Experimental on that MDN page—still unsuitable as a cross-browser dependency.
• Always feature-detect; provide pageY / offsetY fallbacks.
• Related: layerX, metaKey, clientY, MouseEvent(), Window, JavaScript hub.

💡 Best Practices