MouseEvent.y — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.y

Beschreibung

MouseEvent.y ist ein Alias für MouseEvent.clientY. Die Eigenschaft liefert die vertikale Koordinate des Mauszeigers zum Zeitpunkt des Ereignisses, gemessen in CSS-Pixeln relativ zur oberen Kante des sichtbaren Bereichs (Viewport) – nicht relativ zum gesamten Dokument.

Die Eigenschaft ist schreibgeschützt und steht in allen Ereignissen zur Verfügung, die von MouseEvent erben, also auch bei PointerEvent, WheelEvent und DragEvent. Zusammen mit MouseEvent.x (Alias für clientX) eignet sie sich z. B. zum Positionieren von Tooltips, Kontextmenüs oder Elementen mit position: fixed.

Da das Scrollen der Seite den Wert nicht beeinflusst, muss man für dokumentbezogene Koordinaten MouseEvent.pageY verwenden oder window.scrollY addieren. Für Koordinaten relativ zum Zielelement bietet sich offsetY bzw. eine Berechnung mit getBoundingClientRect() an.

Rückgabewert

Typ

number

Beschreibung

Vertikale Position des Mauszeigers in CSS-Pixeln relativ zum Viewport (identisch mit clientY). Laut Spezifikation ein double, kann also Nachkommastellen enthalten.

Beispiele

Mausposition beim Klick ausgeben

document.addEventListener('click', (event) => {
  console.log(`x: ${event.x}, y: ${event.y}`);
  // y ist identisch mit clientY
  console.log(event.y === event.clientY);
});

x: 240, y: 118 true

Tooltip am Mauszeiger mitführen

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

const onMove = (event) => {
  // fixed-Positionierung passt direkt zu Viewport-Koordinaten
  tooltip.style.left = `${event.x + 12}px`;
  tooltip.style.top = `${event.y + 12}px`;
};

document.addEventListener('mousemove', onMove);
// Später wieder entfernen:
// document.removeEventListener('mousemove', onMove);

Viewport-, Dokument- und Element-Koordinaten vergleichen

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

box.addEventListener('pointerdown', (event) => {
  const rect = box.getBoundingClientRect();
  console.log('Viewport (y):', event.y);
  console.log('Dokument (pageY):', event.pageY, '=', event.y + window.scrollY);
  console.log('Im Element:', event.y - rect.top);
});

Viewport (y): 150 Dokument (pageY): 950 = 950 Im Element: 30

// Wichtig · Fallstricke

Viewport, nicht Dokument: Ist die Seite gescrollt, weicht y von pageY ab. Für absolute Positionierung im Dokument (position: absolute) pageY verwenden.
Lesbarkeit: clientY ist im Code aussagekräftiger und wird häufiger verwendet; y ist ein kurzer Alias ohne zusätzliche Funktion.
Kompatibilität: Ältere Firefox-Versionen (vor 63) und der Internet Explorer unterstützen MouseEvent.y nicht bzw. nicht einheitlich. Für maximale Kompatibilität clientY nutzen.
Nachkommastellen: Der Wert kann gebrochen sein (z. B. bei Zoom oder hochauflösenden Displays). Beim Vergleichen gegebenenfalls runden.
Bei Touch-Ereignissen (TouchEvent) existiert y nicht; dort event.touches[0].clientY verwenden oder auf PointerEvent umsteigen.

Siehe auch

MouseEvent.x MouseEvent.clientY MouseEvent.pageY MouseEvent.screenY MouseEvent.offsetY MouseEvent Element.getBoundingClientRect()