MouseEvent.x — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.x

Beschreibung

Die Eigenschaft MouseEvent.x ist ein Alias für MouseEvent.clientX. Sie liefert die horizontale Koordinate des Mauszeigers zum Zeitpunkt des Ereignisses, gemessen in CSS-Pixeln vom linken Rand des Viewports, also des sichtbaren Bereichs des Dokuments. Das Scrollen der Seite verändert den Wert nicht: Ein Klick ganz links im sichtbaren Bereich liefert immer ungefähr 0, egal wie weit die Seite gescrollt ist.

Ursprünglich stammt x aus dem alten Internet Explorer. Später wurde die Eigenschaft in die Spezifikation CSSOM View übernommen, damit sie zum Interface DOMRect passt, das ebenfalls x und y hat. So lässt sich die Mausposition direkt mit Werten aus getBoundingClientRect() vergleichen, denn beide beziehen sich auf den Viewport.

Weil MouseEvent die Basis für PointerEvent, WheelEvent und DragEvent ist, gibt es x auch bei diesen Ereignissen. Nutzen Sie die Eigenschaft, wenn Sie Elemente mit position: fixed am Zeiger ausrichten möchten, etwa für Tooltips oder Kontextmenüs, oder wenn Sie Treffer gegen Rechtecke aus getBoundingClientRect() prüfen. Für Koordinaten relativ zum gesamten Dokument verwenden Sie pageX, für Koordinaten relativ zum Zielelement offsetX.

Rückgabewert

Typ

number

Beschreibung

Horizontale Position in CSS-Pixeln relativ zum Viewport. Der Wert ist identisch mit clientX. Laut Spezifikation ist er ein double und kann daher Nachkommastellen haben, etwa bei Zoom oder hochauflösenden Displays. Die Eigenschaft ist schreibgeschützt.

Beispiele

Mausposition beim Klick ausgeben

document.addEventListener('click', (event) => {
  // x und clientX liefern denselben Wert
  console.log(`x: ${event.x}, clientX: ${event.clientX}`);
  console.log(event.x === event.clientX);
});

x: 312, clientX: 312 true

Tooltip mit position: fixed am Mauszeiger ausrichten

const tooltip = document.createElement('div');
tooltip.textContent = 'Hinweis';
Object.assign(tooltip.style, { position: 'fixed', pointerEvents: 'none' });
document.body.append(tooltip);

document.addEventListener('mousemove', ({ x, y }) => {
  // Viewport-Koordinaten passen direkt zu position: fixed
  tooltip.style.left = `${x + 12}px`;
  tooltip.style.top = `${y + 12}px`;
});

Treffertest mit getBoundingClientRect()

const box = document.querySelector('#zielbereich');

document.addEventListener('pointerdown', (event) => {
  const rect = box.getBoundingClientRect();
  // Beide Werte beziehen sich auf den Viewport
  const drinnen =
    event.x >= rect.left && event.x <= rect.right &&
    event.y >= rect.top && event.y <= rect.bottom;
  console.log(drinnen ? 'Im Zielbereich' : 'Außerhalb');
});

Im Zielbereich

Position relativ zum Element berechnen

const canvas = document.querySelector('canvas');

canvas.addEventListener('click', (event) => {
  const rect = canvas.getBoundingClientRect();
  const relX = event.x - rect.left;
  console.log(`Klick bei ${relX.toFixed(1)} px vom linken Canvas-Rand`);
});

Klick bei 148.0 px vom linken Canvas-Rand

// Wichtig · Fallstricke

Nur ein Alias: x und clientX sind immer identisch. Für klaren, gut lesbaren Code gilt clientX oft als eindeutiger, weil sofort erkennbar ist, auf welchen Bezugsrahmen sich der Wert bezieht.
Scrollen nicht vergessen: x bezieht sich auf den Viewport, nicht auf das Dokument. Für Positionen relativ zum Dokument verwenden Sie pageX bzw. clientX + window.scrollX.
Kompatibilität: In aktuellen Browsern wird x überall unterstützt. Firefox unterstützt es erst ab Version 63. Sehr alte Browser und manche nachgebildeten Ereignisobjekte, etwa in Testumgebungen wie älteren jsdom-Versionen, kennen es möglicherweise nicht. Nutzen Sie dort clientX.
Synthetische Ereignisse: Bei new MouseEvent('click', { clientX: 50 }) wird x automatisch auf 50 gesetzt. Eine eigene Initialisierungsoption x gibt es nicht.
Touch: TouchEvent erbt nicht von MouseEvent und hat deshalb kein x. Verwenden Sie event.touches[0].clientX oder gleich Pointer-Ereignisse.
Der Wert kann Nachkommastellen haben. Runden Sie ihn bei Bedarf mit Math.round().

Siehe auch

MouseEvent.clientX MouseEvent.y MouseEvent.pageX MouseEvent.offsetX MouseEvent.screenX Element.getBoundingClientRect() MouseEvent