JavaScript MouseEvent movementY Property

What You’ll Learn

MouseEvent.movementY is a read-only number: how far the pointer moved vertically since the previous move event. Learn when it is non-zero, how it relates to screenY, unit caveats, safer DIY deltas, and five try-it labs.

Introduction

Absolute positions like clientY answer “where is the cursor?” movementY answers “how far did it move up or down since the last move?”—perfect for pans, look controls, and drawing tools.

document.addEventListener("mousemove", (event) => {
  console.log(event.movementY); // delta since previous mousemove
});

Understanding the Property

MDN: movementY provides the difference in the Y coordinate of the mouse (or pointer) between the given move event and the previous move event of the same type. In other words, it is computed like currentEvent.screenY - previousEvent.screenY.

• Instance — read event.movementY in a handler.
• Delta — positive when moving down, negative when moving up (typical).
• Move-only — zero on click and most other mouse events.
• Unit caution — browsers may disagree on pixel units (see Notes).

📝 Syntax

const dy = mouseEvent.movementY;

Value

A number for the vertical movement since the previous same-type move event. Always 0 on other MouseEvent types (and on pointer events other than pointermove / pointerrawupdate).

Safer DIY delta (portable units)

let prevScreenY = null;

document.addEventListener("mousemove", (e) => {
  const dy = prevScreenY == null ? 0 : e.screenY - prevScreenY;
  prevScreenY = e.screenY;
  console.log({ movementY: e.movementY, diyDy: dy });
});

⚖️ movementY vs Absolute Y Properties

Examples Gallery

Examples follow MDN MouseEvent.movementY. Move the mouse to see non-zero deltas; click to confirm zeros.

const log = document.getElementById("log");

function logMovement(event) {
  log.insertAdjacentHTML(
    "afterbegin",
    `movement: ${event.movementX}, ${event.movementY}
`
  );
  while (log.childNodes.length > 128) log.lastChild.remove();
}

document.addEventListener("mousemove", logMovement);

movement: 3, 0
movement: 5, 1
movement: 2, -1

document.addEventListener("click", (e) => {
  console.log({
    type: e.type,
    movementY: e.movementY, // 0
    clientY: e.clientY      // absolute position still set
  });
});

{
  type: "click",
  movementY: 0,
  clientY: 214
}

let prev = null;

document.addEventListener("mousemove", (e) => {
  const diyDy = prev == null ? 0 : e.screenY - prev;
  prev = e.screenY;
  console.log({ movementY: e.movementY, diyDy });
});

{
  movementY: 4,
  diyDy: 4
}

let traveled = 0;
const out = document.getElementById("out");

document.addEventListener("mousemove", (e) => {
  traveled += Math.abs(e.movementY);
  out.textContent = `Vertical travel ≈ ${Math.round(traveled)}`;
});

Vertical travel ≈ 842

const box = document.getElementById("box");
let dragging = false;
let y = 40;

box.addEventListener("mousedown", () => { dragging = true; });
window.addEventListener("mouseup", () => { dragging = false; });

window.addEventListener("mousemove", (e) => {
  if (!dragging) return;
  y += e.movementY;
  box.style.transform = `translateY(${y}px)`;
});

Box follows vertical drag using movementY deltas.

🚀 Common Use Cases

• Pointer-lock look / camera controls in games.
• Canvas drawing tools that react to stroke velocity or direction.
• Drag-to-pan maps, timelines, and image viewers.
• Gesture metrics (how far the cursor traveled this frame).
• Teaching relative vs absolute mouse coordinates next to clientY.

🔧 How It Works

📝 Notes

• Baseline Newly available (MDN, since January 2026)—verify older browsers if needed.
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• MDN warning: unit systems for movementY / screenY can differ by browser and OS.
• Prefer DIY screenY/clientY deltas when pixel units must match everywhere.
• Related: movementX, clientY, MouseEvent(), Window, JavaScript hub.

💡 Best Practices