JavaScript MouseEvent metaKey Property

What You’ll Learn

MouseEvent.metaKey is a read-only boolean: true if the Meta key was held when the mouse event fired. Learn Command vs Windows-key mapping, OS shortcut caveats, Command+click patterns, synthetic events, and five try-it labs.

Introduction

On Mac, Command+click is the familiar “open related” / multi-select pattern. That key state is exposed as metaKey. On Windows, the same property tracks the Windows key—but the OS often claims that key for itself.

element.addEventListener("click", (event) => {
  console.log(event.metaKey); // true or false
});

Understanding the Property

MDN: MouseEvent.metaKey is a read-only boolean that indicates whether the meta key was pressed when a given mouse event occurred.

• Instance — read event.metaKey inside a handler.
• Boolean — true pressed, false not pressed.
• Read-only — set via constructor options on synthetic events.
• OS may intercept — Meta often triggers system UI before your page sees it.

📝 Syntax

const isMetaHeld = mouseEvent.metaKey;

Value

A boolean: true if Meta was held during the event; otherwise false.

Setting it on synthetic events

const event = new MouseEvent("click", {
  metaKey: true,
  bubbles: true
});
console.log(event.metaKey); // true

⚖️ Related Modifier Properties

You can also call event.getModifierState("Meta") for a related check.

Examples Gallery

Examples follow MDN MouseEvent.metaKey. Hold ⌘ (Mac) or try Meta on your platform while clicking to see true (OS caveats apply).

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

document.addEventListener("click", (e) => {
  log.textContent = `The meta key is pressed: ${e.metaKey}`;
});

The meta key is pressed: false

link.addEventListener("click", (e) => {
  if (e.metaKey || e.ctrlKey) {
    // Command (Mac) or Control (Win/Linux)
    console.log("modifier+click — open related view");
    return;
  }
  console.log("Normal click — default action");
});

Normal click — default action

const event = new MouseEvent("click", {
  metaKey: true,
  bubbles: true
});

console.log(event.metaKey);     // true
console.log(event.type);        // "click"
console.log(event instanceof MouseEvent); // true

true
click
true

document.addEventListener("click", (e) => {
  console.log({
    metaKey: e.metaKey,
    ctrlKey: e.ctrlKey,
    altKey: e.altKey,
    shiftKey: e.shiftKey
  });
});

{
  metaKey: false,
  ctrlKey: false,
  altKey: false,
  shiftKey: false
}

const event = new MouseEvent("click", { metaKey: true });

console.log(event.metaKey);                   // true
console.log(event.getModifierState("Meta"));   // true
console.log(event.metaKey === event.getModifierState("Meta")); // true

true
true
true

🚀 Common Use Cases

• Command+click secondary actions and multi-select on Mac.
• Cross-platform power-clicks with metaKey || ctrlKey.
• Unit tests that construct MouseEvent with metaKey: true.
• Detecting Meta-aware shortcuts (when the OS does not steal the key).
• Teaching the modifier family next to ctrlKey and altKey.

🔧 How It Works

📝 Notes

• Baseline Widely available (MDN, since July 2015).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Mac Meta = Command (⌘); Windows Meta = Windows key (⊞).
• OS shortcuts may keep metaKey false even when the key is held.
• Related: layerY, movementX, ctrlKey, altKey, MouseEvent(), Window, JavaScript hub.

💡 Best Practices