Mouse events

Almost every interface you build reacts to a pointer moving and clicking. This chapter takes the mouse events you’ve already met and fills in the parts that trip people up: exactly which events fire and in what order, how to tell the left button from the right, which modifier keys were held down, and the two coordinate systems every mouse event carries.

One thing to keep in mind before the details. These events don’t only come from an actual mouse. Phones, tablets, and trackpads generate them too. When you tap a touchscreen, the browser fires a matching set of mouse events so that pages written for a mouse keep working. So “mouse event” is really about a pointing action, not a physical mouse.

Mouse event types

You’ve seen several of these already. Here’s the full cast for this chapter.

There are more mouse-related events (the mouseenter/mouseleave pair, drag events, and so on) that later chapters cover. The list above is enough to reason about a normal click.

Events order

A single user action often triggers a sequence of events, not one. Press and release the left button, and three events fire in a row.

When one action produces several events, the browser fires them in a fixed order. For a left click that order is always mousedown → mouseup → click.

A double click layers on top of this. Each of the two clicks fires its own full mousedown → mouseup → click sequence, and only after the second one does dblclick fire. So a double click is a fairly busy stream of events.

To watch this live, wire one handler to several events on a single target and print each one into a log as it fires. Click the box below with the left button and you’ll see the mousedown → mouseup → click trio arrive. Try the right button for mousedown → mouseup → contextmenu. Double-click to watch two full sequences land before dblclick. The log also prints each event’s button value (explained next) and drops a divider whenever more than a second passes between events.

<div id="probe">Click me — left, right, or double</div>
<button id="clear">Clear log</button>
<textarea id="log" readonly rows="7"></textarea>

#probe {
user-select: none;
padding: 22px;
text-align: center;
border: 2px dashed #a78bfa;
border-radius: 10px;
background: #faf5ff;
color: #6d28d9;
font-weight: 600;
cursor: pointer;
}
button { margin: 10px 0; padding: 6px 12px; border: 1px solid #d4d4d8; border-radius: 6px; background: #fff; cursor: pointer; }
textarea { display: block; width: 100%; box-sizing: border-box; font: 13px ui-monospace, monospace; }

const probe = document.getElementById('probe');
const log = document.getElementById('log');
let last = 0;

function write(e) {
const now = Date.now();
if (last && now - last > 1000) log.value += '—————\n';
last = now;
log.value += e.type.padEnd(12) + ' button=' + e.button + '\n';
log.scrollTop = log.scrollHeight;
}

['mousedown', 'mouseup', 'click', 'dblclick'].forEach(function (t) {
probe.addEventListener(t, write);
});
probe.addEventListener('contextmenu', function (e) {
write(e);
e.preventDefault(); // keep the real menu from covering the demo
});
document.getElementById('clear').addEventListener('click', function () {
log.value = '';
last = 0;
});

Mouse button

Every click-related event carries a button property telling you which physical button was involved.

You usually don’t need it for click or contextmenu: click only ever fires for the left button, and contextmenu is tied to the right button (or the menu key). The property earns its keep on mousedown and mouseup, which fire for any button. There, event.button is how you separate a right-button press from a left-button press.

The possible values:

Most mice only have left and right buttons, so in practice you’ll see 0 or 2. Touch devices produce equivalent events when someone taps.

Modifiers: shift, alt, ctrl and meta

Every mouse event also records which modifier keys were held while it fired. Four boolean properties:

• event.shiftKey — Shift
• event.altKey — Alt (or Opt on Mac)
• event.ctrlKey — Ctrl
• event.metaKey — Cmd on Mac

Each is true if that key was down at the moment of the event. That lets you build shortcuts like Alt+Shift+click. This button only reacts when both are held:

<button id="unlock">Alt+Shift+Click to unlock</button>

<script>
  unlock.onclick = function(event) {
    if (event.altKey && event.shiftKey) {
      alert('Panel unlocked!');
    }
  };
</script>

Try it below. Hold different combinations of keys while you click and watch the four boolean flags flip. The button only unlocks when both Alt and Shift are down at the moment of the click:

<button id="combo">Alt + Shift + Click me</button>
<div id="flags">shift: false · alt: false · ctrl: false · meta: false</div>
<div id="verdict">Holding the right keys?</div>

button { padding: 10px 16px; font-size: 15px; border: 1px solid #d4d4d8; border-radius: 8px; background: #fff; cursor: pointer; }
#flags { margin-top: 12px; font: 13px ui-monospace, monospace; color: #52525b; }
#verdict { margin-top: 6px; font-weight: 600; color: #b45309; }
#verdict.win { color: #15803d; }

const btn = document.getElementById('combo');
const flags = document.getElementById('flags');
const verdict = document.getElementById('verdict');

btn.addEventListener('click', function (event) {
flags.textContent =
  'shift: ' + event.shiftKey +
  ' · alt: ' + event.altKey +
  ' · ctrl: ' + event.ctrlKey +
  ' · meta: ' + event.metaKey;

if (event.altKey && event.shiftKey) {
  verdict.textContent = 'Unlocked! Alt and Shift were both held.';
  verdict.className = 'win';
} else {
  verdict.textContent = 'Not yet — hold Alt and Shift together, then click.';
  verdict.className = '';
}
});

Coordinates: clientX/Y, pageX/Y

Every mouse event reports where the pointer was, in two coordinate systems at once:

1. Window-relative — event.clientX and event.clientY, measured from the top-left of the visible area.
2. Document-relative — event.pageX and event.pageY, measured from the top-left of the whole document.

The full story is in the Coordinates chapter. The short version: pageX/Y are anchored to the document, so scrolling doesn’t change them for a given spot in the content. clientX/Y are measured from the current viewport, so they do change as you scroll, the same way position:fixed stays put relative to the window.

Picture a 500×500 window. If the pointer sits in the top-left corner, clientX and clientY are both 0, no matter how far the page is scrolled. In the center they’re both 250, again independent of scroll. That’s the “fixed to the window” behavior.

To see clientX/Y change as you move, print them from a mousemove handler. Glide the pointer across the pad below — the readout updates on every move, and a dot tracks your position inside the box:

<div id="pad">Move the pointer across this pad
<span id="dot"></span>
</div>
<div id="read">clientX: — , clientY: —</div>

#pad {
position: relative;
height: 150px;
border: 2px solid #38bdf8;
border-radius: 10px;
background: #f0f9ff;
color: #0369a1;
text-align: center;
padding-top: 12px;
overflow: hidden;
cursor: crosshair;
}
#dot {
position: absolute;
width: 12px; height: 12px;
margin: -6px 0 0 -6px;
border-radius: 50%;
background: #0284c7;
pointer-events: none;
display: none;
}
#read { margin-top: 12px; font: 14px ui-monospace, monospace; color: #334155; }

const pad = document.getElementById('pad');
const dot = document.getElementById('dot');
const read = document.getElementById('read');

pad.addEventListener('mousemove', function (event) {
read.textContent = 'clientX: ' + event.clientX + ' , clientY: ' + event.clientY;
const box = pad.getBoundingClientRect();
dot.style.left = (event.clientX - box.left) + 'px';
dot.style.top = (event.clientY - box.top) + 'px';
dot.style.display = 'block';
});
pad.addEventListener('mouseout', function () {
dot.style.display = 'none';
});

Preventing selection on mousedown

Double clicks have an annoying side effect: they select text. Double-click the word below and the browser highlights it, right alongside whatever your handler does:

<span ondblclick="alert('dblclick')">Double-click me</span>

Pressing the left button and dragging does the same thing — it starts a text selection, which is usually unwanted inside interactive widgets like a custom slider or a sortable list.

There are several ways to stop selection, covered in Selection and Range. For this specific problem the cleanest fix is to cancel the browser’s default action on mousedown, which is what starts a selection. Return false from the handler:

Before...
<b ondblclick="alert('Click!')" onmousedown="return false">
  Double-click me
</b>
...After

Now double-clicking the bold text won’t highlight it, and press-and-drag on it won’t begin a selection either.

Compare the two directly. Double-click (or press and drag across) each label below. The first selects text the usual way; the second cancels the default on mousedown, so no highlight appears:

<p>Double-click or drag across each label:</p>
<span id="normal">I select normally</span>
<span id="guarded">I refuse to be selected</span>

span {
display: inline-block;
margin: 6px 8px 0 0;
padding: 10px 14px;
border-radius: 8px;
font-weight: 600;
cursor: pointer;
}
#normal { background: #fee2e2; color: #991b1b; }
#guarded { background: #dcfce7; color: #166534; }

// The guarded label cancels mousedown's default action, which is
// what would otherwise start a text selection.
document.getElementById('guarded').addEventListener('mousedown', function (event) {
event.preventDefault();
});

The text inside is still selectable — you just can’t begin a selection on the element itself. A user can start selecting before or after it and drag across, which is normally fine.

Summary

Mouse events hand you a consistent set of properties:

• Which button: event.button (0 left, 1 middle, 2 right, 3/4 side buttons). Needed mainly on mousedown/mouseup, which fire for any button. There’s also a plural event.buttons bitmask for combinations, rarely needed.
• Modifier keys (true when held): event.altKey, event.ctrlKey, event.shiftKey, and event.metaKey (Mac’s Cmd). For a Ctrl shortcut, check if (event.ctrlKey || event.metaKey) so Mac users get Cmd, and always leave a path for devices with no keyboard.
• Window-relative coordinates: event.clientX / event.clientY, unaffected by scroll.
• Document-relative coordinates: event.pageX / event.pageY, anchored to the document.

Events from one action fire in a fixed order — mousedown → mouseup → click for a left click. The default action of mousedown is to begin text selection; cancel it when that gets in the way of your interface.

Next up: the events that track the pointer moving across elements, and how to follow what’s underneath it.