JavaScript MouseEvent layerX Property

What You’ll Learn

MouseEvent.layerX is a non-standard read-only X coordinate relative to the current “layer.” Learn how positioned elements change its meaning, how it compares to pageX, 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.layerX); // non-standard — may be undefined
});

Understanding the Property

MDN: MouseEvent.layerX returns the horizontal 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.layerX in a handler.
• Integer pixels — X when the mouse event fired (when supported).
• Non-standard — not in any official specification.
• Position-sensitive — meaning changes inside positioned elements.

📝 Syntax

const x = mouseEvent.layerX;

Value

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

Safe read with fallback

function getX(event) {
  if (typeof event.layerX === "number") {
    return event.layerX; // legacy / non-standard
  }
  return event.pageX; // standard fallback
}

⚖️ layerX vs Standard Coordinates

Examples Gallery

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

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

142
# or: layerX not available

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

{
  layerX: 220,
  pageX: 220
}

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

{
  layerX: 12,
  pageX: 640,
  offsetX: 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 pointerX(event, mode = "page") {
  if (mode === "client") return event.clientX;
  if (mode === "offset") return event.offsetX;
  return event.pageX; // default: document
}

document.addEventListener("mousedown", (e) => {
  console.log({
    page: pointerX(e, "page"),
    client: pointerX(e, "client"),
    offset: pointerX(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 offsetX, pageX, or clientX.
• 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 pageX / offsetX fallbacks.
• Related: ctrlKey, layerY, clientX, MouseEvent(), Window, JavaScript hub.

💡 Best Practices