JavaScript MouseEvent buttons Property

Beginner
5 min read
Updated: Nov 2026
5 examples
Property
Decorative image with the word BUTTONS

Definition

The read-only buttons property is a bit-field number for which mouse buttons are held when the event fires (MDN). Multiple buttons add together (left 1 + right 2 = 3). Do not confuse it with button (which button just changed).

Read the notes below before you rely on this property. Prefer feature detection when support is limited.

Syntax

Use event.buttons. Start with this line.

JavaScript
event.buttons
CallWhat it does
event.buttonsPrimary signature.

Built into the browser. Read event.buttons on a MouseEvent — no import required.

Library declarations
JavaScript
event.buttons

Parameters

This member has no parameters beyond those shown in the signature.

Return Value

Return ValueDescription
*Number bit-field (0, 1, 2, 4, ...)

JavaScript Examples

Example 1 — Log buttons (MDN-style)

Print the bit-field on press and release.

JavaScript
function logButtons(event) {
  console.log(event.type, event.buttons);
}

el.addEventListener("mousedown", logButtons);
el.addEventListener("mouseup", logButtons);
Try It Yourself

How It Works

  1. Listen for press and release. Both carry buttons.
  2. On mousedown left: usually 1 (left held).
  3. On mouseup: often 0 (nothing held).
  4. Matches MDN’s idea of logging held state.

Example 2 — Bitwise Left Check

MDN pattern: test one button with & and a power of two.

JavaScript
el.addEventListener("mousedown", (e) => {
  const leftHeld = (e.buttons & 1) !== 0;
  console.log("left held?", leftHeld);
});
Try It Yourself

How It Works

  1. Left bit is 1. Mask with & 1.
  2. Non-zero means held. Compare to 0.
  3. Right uses & 2; middle uses & 4.
  4. Works even when several buttons are held at once.

Example 3 — Combined Value

When two buttons are held, values add (e.g. left + right = 3).

JavaScript
el.addEventListener("mousedown", (e) => {
  console.log("buttons", e.buttons);
  if (e.buttons === 3) {
    console.log("left + right held");
  }
});
Try It Yourself

How It Works

  1. Hold more than one button. Bits combine.
  2. 1 + 2 = 3. Left and right together.
  3. Exact equals works for a known combo.
  4. Prefer & checks when you only care about one bit.

Example 4 — Drag While Left Held

Use buttons on mousemove — where button is not reliable.

JavaScript
el.addEventListener("mousemove", (e) => {
  if ((e.buttons & 1) === 0) return;
  console.log("dragging", e.clientX, e.clientY);
});
Try It Yourself

How It Works

  1. mousemove fires often. Check held state each time.
  2. Require left bit. Skip when not dragging.
  3. Why not button? MDN: button is not reliable on move.
  4. clientX / clientY give the drag position.

Example 5 — Synthetic MouseEvent

Set buttons in constructor options for tests.

JavaScript
const e = new MouseEvent("mousemove", { buttons: 1 });
console.log(e.buttons); // 1
Try It Yourself

How It Works

  1. new MouseEvent with buttons: 1.
  2. No physical mouse needed for the synthetic event.
  3. e.buttons is 1 (left held).
  4. Also set button if your handler reads the changed-button property.
Compatibility

Browser Support

MouseEvent.buttons is marked Baseline Widely available on MDN (since April 2018).

✓ Baseline · Widely available

MouseEvent.buttons

Bit-field of held mouse buttons. Broader than button for drag/move. Safe everyday DOM API.

100% Widely available
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
buttons Excellent

Bottom line: Safe everyday API. Remember bits add (1+2=3). See the MDN buttons reference.

Frequently Asked Questions

It is a read-only number that is a bit-field of which mouse buttons are currently pressed when the event fires. Values add together—for example left (1) + right (2) = 3.
No. MDN marks MouseEvent.buttons as Baseline Widely available (since April 2018). It is not Deprecated, Experimental, or Non-standard.
button is which button changed (0 left, 1 middle, 2 right) and is reliable mainly on press/release events. buttons is which buttons are held (1 left, 2 right, 4 middle) and works across mouse event types, including mousemove.
Use a bitwise AND: (event.buttons & 1) !== 0. For right use & 2, for middle & 4.
Because bits add: secondary (2) + auxiliary/middle (4) = 6 when both are held at once.
Pass buttons in MouseEvent options, for example new MouseEvent("mousemove", { buttons: 1 }) to simulate left held while moving.

Next: clientX

Read the mouse X coordinate relative to the viewport.

clientX tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

9 people found this page helpful

JavaScript MouseEvent button Property JavaScript MouseEvent clientX Property