JavaScript MouseEvent button Property

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

Definition

The read-only button property is a number for which mouse button was pressed or released to trigger the event (MDN). Do not confuse it with buttons (which buttons are currently held).

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

Syntax

Use event.button. Start with this line.

JavaScript
event.button
CallWhat it does
event.buttonPrimary signature.

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

Library declarations
JavaScript
event.button

Parameters

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

Return Value

Return ValueDescription
*Number 0–4 (common)

JavaScript Examples

Example 1 — mouseup Switch

MDN pattern: map button to a short message.

JavaScript
el.addEventListener("mouseup", (e) => {
  switch (e.button) {
    case 0: console.log("Left"); break;
    case 1: console.log("Middle"); break;
    case 2: console.log("Right"); break;
    default: console.log("Other", e.button);
  }
});
Try It Yourself

How It Works

  1. Listen for mouseup. Fires when a button is released.
  2. Read e.button. Which button changed.
  3. switch cases. Map 0 / 1 / 2 to labels.
  4. default covers Back/Forward or odd devices.

Example 2 — Main Button Only

Ignore non-main clicks with a simple guard.

JavaScript
el.addEventListener("mousedown", (e) => {
  if (e.button !== 0) return;
  console.log("main button down");
});
Try It Yourself

How It Works

  1. Use mousedown. Reliable press event.
  2. Require button === 0. Main / left action.
  3. Early return for middle/right.
  4. 0 means main action — not always physical leftmost.

Example 3 — Right Button + contextmenu

Detect right press/release; often block the default menu while testing.

JavaScript
el.addEventListener("mouseup", (e) => {
  if (e.button === 2) console.log("Right");
});
el.addEventListener("contextmenu", (e) => {
  e.preventDefault();
});
Try It Yourself

How It Works

  1. button === 2 is secondary / right.
  2. contextmenu often follows a right click.
  3. preventDefault stops the browser menu (as in MDN demo).
  4. Use carefully — users expect a context menu.

Example 4 — button vs buttons

Changed button vs currently held bitmask (different numbers).

JavaScript
el.addEventListener("mousedown", (e) => {
  console.log("button", e.button);
  console.log("buttons", e.buttons);
});
Try It Yourself

How It Works

  1. button — which button just changed (0 left).
  2. buttons — bit-field of held buttons (1 = left held).
  3. Numbers differ — do not compare them as equals.
  4. Prefer buttons when tracking drag with held state.

Example 5 — Synthetic MouseEvent

Set button in constructor options for tests.

JavaScript
const e = new MouseEvent("mouseup", { button: 2 });
console.log(e.button); // 2
Try It Yourself

How It Works

  1. new MouseEvent with button: 2.
  2. No physical mouse needed for the synthetic event.
  3. e.button is 2 (secondary / right).
  4. Also set buttons if your handler reads the bitmask.
Compatibility

Browser Support

MouseEvent.button is marked Baseline Widely available on MDN (since July 2015).

✓ Baseline · Widely available

MouseEvent.button

Number for which button was pressed or released. Prefer mousedown/mouseup. Do not confuse with buttons.

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
button Excellent

Bottom line: Safe everyday API on press/release events. See the MDN button reference.

Frequently Asked Questions

A read-only number that indicates which button was pressed or released to trigger that event. Common values: 0 main/left, 1 auxiliary/middle, 2 secondary/right, 3 back, 4 forward.
No. MDN marks MouseEvent.button as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
button tells which button changed for press/release-related events. buttons is a bit-field of which buttons are currently held and can be used more broadly across mouse event types.
MDN says it only guarantees meaning during events caused by pressing or releasing buttons. It is not reliable for mouseenter, mouseleave, mouseover, mouseout, or mousemove.
Not necessarily. Remapped devices (for example left-handed layouts) may reverse physical buttons. Value 0 means the main button action—usually left in a standard layout.
Pass button in the options to new MouseEvent("mouseup", { button: 2 }). Remember button and buttons use different number systems.

Next: buttons

Learn the bit-field for which mouse buttons are currently held.

buttons 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)

8 people found this page helpful

JavaScript MouseEvent altKey Property JavaScript MouseEvent buttons Property