CKTIS / JavaScript
MouseEvent: mouse buttons and modifier keys
Read which mouse button an event concerns and whether Ctrl, Meta, Shift, or Alt was active. Use `buttons`, not `button`, to test which buttons are held.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
event.button
event.ctrlKey
event.metaKey
event.shiftKey
event.altKeyMouseEvent.button/ctrlKey/metaKey/shiftKey/altKey refers to five read-only instance properties. Read them on the event object, for example event.button. They belong to the Web API, not ECMAScript 2024, so availability depends on the runtime.
For button press or release events such as mousedown and mouseup, button is a single code: 0 primary (usually left), 1 auxiliary (usually middle), 2 secondary (usually right), 3 fourth (typically Back), 4 fifth (typically Forward). These are roles, not physical positions. On mousemove, button is not a reliable indicator of a held button. buttons is a bitmask of held buttons: 0 means none, and 1, 2, 4, 8, 16 represent primary, secondary, auxiliary, fourth, and fifth respectively. (event.buttons & 1) !== 0 tests the primary-button bit.
ctrlKey reports Ctrl, metaKey reports Meta (Command on macOS, the Windows key on Windows), shiftKey reports Shift, and altKey reports Alt (Option on macOS). Each is true if the event reports that modifier as down and false otherwise. This is a snapshot for the event, not a live keyboard query. The OS can intercept a gesture: on macOS, Ctrl-click can open a context menu instead of delivering an ordinary click. A click alone does not prove a mouse was used: it can also come from a keyboard or touch input.
In new MouseEvent(type, options), omitted button and buttons options default to 0, and omitted modifier options default to false. A synthetic event has isTrusted === false and does not grant the user activation required by some APIs.
Examples
// Use native MouseEvent in browsers. In Node.js, model only the fields read below.
const DemoMouseEvent = globalThis.MouseEvent ?? class extends Event {
constructor(type, {
button = 0, buttons = 0,
ctrlKey = false, metaKey = false, shiftKey = false, altKey = false,
} = {}) {
super(type);
const fields = { button, buttons, ctrlKey, metaKey, shiftKey, altKey };
for (const [key, value] of Object.entries(fields)) {
Object.defineProperty(this, key, { value });
}
}
};
for (const event of [
new DemoMouseEvent("mousedown", { button: 1, buttons: 6, ctrlKey: true, shiftKey: true }),
new DemoMouseEvent("mousemove", { buttons: 2, metaKey: true, altKey: true }),
]) {
const { type, button, buttons, ctrlKey, metaKey, shiftKey, altKey } = event;
console.log(JSON.stringify({ type, button, buttons, ctrlKey, metaKey, shiftKey, altKey }));
}Result
{"type":"mousedown","button":1,"buttons":6,"ctrlKey":true,"metaKey":false,"shiftKey":true,"altKey":false}
{"type":"mousemove","button":0,"buttons":2,"ctrlKey":false,"metaKey":true,"shiftKey":false,"altKey":true}Run this in a browser console. In the first line, `button: 1` identifies the auxiliary button, and `buttons: 6` combines the secondary (`2`) and auxiliary (`4`) bits. In the second line, `button: 0` is the default, while the mask reports only the secondary button. Neither event is dispatched.
Related lessons
- JavaScript · Lesson 37 · Advanced · Version: 4
- JavaScript · Lesson 38 · Advanced · Version: 4
- JavaScript · Lesson 36 · Intermediate · Version: 3
- JavaScript · Lesson 37 · Intermediate · Version: 3
Sources
- MouseEvent: button property
- MouseEvent: ctrlKey property
- MouseEvent: metaKey property
- MouseEvent: shiftKey property
- MouseEvent: altKey property
- MouseEvent: buttons property
- MouseEvent: MouseEvent() constructor
- Element: click event
- Event: isTrusted property
- HTML Standard: Tracking user activation
- ECMAScript 2024 Language Specification: Hosts and Implementations