JavaScript MouseEvent buttons Property

What You’ll Learn

MouseEvent.buttons is a read-only bit-field: which mouse buttons are held when the event fires. Learn the power-of-two values, how to combine and test bits, how this differs from button, and five try-it labs.

Introduction

While drawing or dragging, you often need “is the left button still down?” on every mousemove. That is what buttons answers: the set of buttons currently pressed, encoded as a single number.

element.addEventListener("mousemove", (event) => {
  console.log(event.buttons); // 0, 1, 2, 3, 4, 5, 6, …
});

Understanding the Property

MDN: MouseEvent.buttons indicates which buttons are pressed when a mouse event is triggered. If more than one is pressed, the values are added together (for example secondary 2 + auxiliary 4 = 6).

• Instance — read event.buttons in a handler.
• Bit-field — powers of two that combine with addition / |.
• Any mouse event — useful on mousemove, unlike button.
• Not button — different property, different number system.

📝 Syntax

const held = mouseEvent.buttons;

Value

A number representing one or more held buttons:

Test a single button

const leftHeld = (event.buttons & 1) === 1;
const rightHeld = (event.buttons & 2) === 2;
const middleHeld = (event.buttons & 4) === 4;

⚖️ buttons vs button

Examples Gallery

Examples follow MDN MouseEvent.buttons. Hold one or more buttons while clicking or moving to see combined values.

const buttonNames = ["left", "right", "wheel", "back", "forward"];

function mouseButtonPressed(event, buttonName) {
  return Boolean(event.buttons & (1 << buttonNames.indexOf(buttonName)));
}

function format(event) {
  const obj = { type: event.type, buttons: event.buttons };
  for (const name of buttonNames) {
    obj[name] = mouseButtonPressed(event, name);
  }
  return JSON.stringify(obj, null, 2);
}

document.addEventListener("mousedown", (e) => {
  console.log(format(e));
});
document.addEventListener("mouseup", (e) => {
  console.log(format(e));
});

{
  "type": "mousedown",
  "buttons": 1,
  "left": true,
  "right": false,
  "wheel": false,
  "back": false,
  "forward": false
}

document.addEventListener("mousedown", (e) => {
  console.log({
    left: (e.buttons & 1) === 1,
    right: (e.buttons & 2) === 2,
    middle: (e.buttons & 4) === 4,
    raw: e.buttons
  });
});

{
  left: true,
  right: false,
  middle: false,
  raw: 1
}

canvas.addEventListener("mousemove", (e) => {
  if ((e.buttons & 1) !== 1) {
    return; // not dragging with left
  }
  console.log("paint at", e.offsetX, e.offsetY);
});

paint at 42 18

const event = new MouseEvent("mousemove", {
  buttons: 3, // 1 + 2
  bubbles: true
});

console.log(event.buttons);              // 3
console.log((event.buttons & 1) === 1);  // true (left)
console.log((event.buttons & 2) === 2);  // true (right)
console.log((event.buttons & 4) === 4);  // false (middle)

3
true
true
false

const leftDown = new MouseEvent("mousedown", {
  button: 0,
  buttons: 1
});

const bothDown = new MouseEvent("mousedown", {
  button: 2,   // right just changed
  buttons: 3   // left + right held
});

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

0 1
2 3

🚀 Common Use Cases

• Canvas painting and drag selection while the pointer moves.
• Detecting multi-button chords (left + right held together).
• Ignoring hover moves when no button is down (buttons === 0).
• Unit tests that synthesize held-button state on mousemove.
• Teaching bit masks with a concrete browser API.

🔧 How It Works

📝 Notes

• Baseline Widely available (MDN, since April 2018).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Remapped / left-handed devices may change which physical button maps to primary.
• Firefox historically had platform quirks (for example very old macOS returning 0); modern browsers are fine for typical use.
• Related: button, clientX, altKey, MouseEvent(), Window, JavaScript hub.

💡 Best Practices