JavaScript MouseEvent button Property

What You’ll Learn

MouseEvent.button is a read-only number that tells you which mouse button was pressed or released to cause the event. Learn the value table, when the property is reliable, how it differs from buttons, and five try-it labs.

Introduction

Left, middle, and right clicks are different actions in many UIs. The browser records which button changed on the event as button—a small integer you can switch on.

element.addEventListener("mouseup", (event) => {
  console.log(event.button); // 0, 1, 2, …
});

Understanding the Property

MDN: MouseEvent.button indicates which button was pressed or released on the mouse to trigger the event. It is reliable for press/release-caused events, not for hover/move events like mousemove or mouseenter.

• Instance — read event.button in a handler.
• Number — usually 0, 1, or 2 for common mice.
• Read-only — set it only via constructor options on synthetic events.
• Layout note — remapped / left-handed devices may swap physical buttons; 0 still means the main button action.

📝 Syntax

const which = mouseEvent.button;

Value

A number representing the button that changed:

⚖️ button vs buttons

Do not confuse the two. Left is button === 0 but buttons & 1 for the held mask.

⚠️ When button Is Reliable

Prefer reading button on events that come from pressing or releasing a button, such as mousedown, mouseup, and often click / auxclick / contextmenu.

MDN: it is not reliable for mouseenter, mouseleave, mouseover, mouseout, or mousemove. For those, use buttons if you need held-button state.

Examples Gallery

Examples follow MDN MouseEvent.button. Try left, middle, and right clicks in the try-it labs.

const button = document.querySelector("#button");
const log = document.querySelector("#log");

button.addEventListener("mouseup", (e) => {
  switch (e.button) {
    case 0:
      log.textContent = "Left button clicked.";
      break;
    case 1:
      log.textContent = "Middle button clicked.";
      break;
    case 2:
      log.textContent = "Right button clicked.";
      break;
    default:
      log.textContent = `Unknown button code: ${e.button}`;
  }
});

button.addEventListener("contextmenu", (e) => {
  e.preventDefault();
});

Left button clicked.

target.addEventListener("mousedown", (e) => {
  if (e.button !== 0) {
    console.log("Ignored non-primary button:", e.button);
    return;
  }
  console.log("Primary (left) press");
});

Primary (left) press

const event = new MouseEvent("mouseup", {
  button: 2,
  bubbles: true
});

console.log(event.button); // 2
console.log(event.type);   // "mouseup"

2
mouseup

const leftDown = new MouseEvent("mousedown", {
  button: 0,   // which changed
  buttons: 1   // left currently held (bit 0)
});

const rightDown = new MouseEvent("mousedown", {
  button: 2,
  buttons: 2   // right held (bit 1)
});

console.log(leftDown.button, leftDown.buttons);   // 0 1
console.log(rightDown.button, rightDown.buttons); // 2 2

0 1
2 2

canvas.addEventListener("mousemove", (e) => {
  // Unreliable for "which button changed":
  // console.log(e.button);

  // Better: are any buttons held while moving?
  const leftHeld = (e.buttons & 1) === 1;
  console.log("dragging with left?", leftHeld);
});

dragging with left? false

🚀 Common Use Cases

• Distinguishing left vs right click in custom UI (with care for accessibility).
• Ignoring non-primary buttons in drawing or drag tools.
• Detecting middle-click (button 1) for open-in-new-tab style actions.
• Unit tests that construct MouseEvent with a specific button.
• Teaching the difference between button and the buttons bit-field.

🔧 How It Works

📝 Notes

• Baseline Widely available (MDN, since July 2015).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Unreliable on mousemove / enter / leave / over / out — use buttons there.
• Value 0 is the main button action, not always the physical leftmost hardware button.
• Related: altKey, buttons, MouseEvent(), addEventListener(), Window, JavaScript hub.

💡 Best Practices