MouseEvent.pageY — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.pageY

Beschreibung

Die schreibgeschützte Eigenschaft pageY des MouseEvent-Interfaces liefert die vertikale Position des Mauszeigers zum Zeitpunkt des Ereignisses in CSS-Pixeln. Bezugspunkt ist der obere Rand des gesamten Dokuments, nicht der sichtbare Ausschnitt. Wurde die Seite um 500 px nach unten gescrollt und klickt der Nutzer 100 px unter dem oberen Fensterrand, ist pageY gleich 600.

Damit gilt im Normalfall: pageY === clientY + window.scrollY. Im Unterschied dazu bezieht sich clientY auf den Viewport, screenY auf den Bildschirm und offsetY auf die Padding-Kante des Zielelements.

pageY eignet sich vor allem dann, wenn Elemente mit position: absolute relativ zum Dokument platziert werden sollen, etwa Tooltips, Kontextmenüs, Markierungen oder Klick-Heatmaps, die unabhängig von der Scrollposition gespeichert werden. Für Elemente mit position: fixed ist dagegen clientY die richtige Wahl.

Die Eigenschaft gibt es auch bei allen abgeleiteten Ereignissen wie PointerEvent, WheelEvent und DragEvent sowie bei Touch-Objekten in TouchEvent.touches.

Rückgabewert

Typ

number

Beschreibung

Ein double-Wert in CSS-Pixeln, der auch Nachkommastellen haben kann: der vertikale Abstand zum oberen Rand des Dokuments. Bei synthetisch erzeugten Ereignissen ohne Koordinaten ist der Wert 0.

Beispiele

Klickposition im Dokument ausgeben

document.addEventListener('click', (event) => {
  console.log(`pageY: ${event.pageY}, clientY: ${event.clientY}, scrollY: ${window.scrollY}`);
});

pageY: 740, clientY: 240, scrollY: 500

Tooltip am Mauszeiger positionieren (position: absolute)

const tooltip = document.createElement('div');
tooltip.textContent = 'Hinweis';
Object.assign(tooltip.style, {
  position: 'absolute',
  pointerEvents: 'none',
  background: '#333',
  color: '#fff',
  padding: '4px 8px',
  display: 'none'
});
document.body.append(tooltip);

const target = document.querySelector('#info');

target.addEventListener('mousemove', (event) => {
  // pageX/pageY passen direkt zu absolut positionierten Elementen im body
  tooltip.style.left = `${event.pageX + 12}px`;
  tooltip.style.top = `${event.pageY + 12}px`;
  tooltip.style.display = 'block';
});

target.addEventListener('mouseleave', () => {
  tooltip.style.display = 'none';
});

Klick-Heatmap unabhängig von der Scrollposition speichern

const clicks = [];

const onClick = ({ pageX, pageY }) => {
  // Relativ zur Dokumenthöhe speichern, damit die Werte auch bei anderer Fenstergröße vergleichbar bleiben
  const docHeight = document.documentElement.scrollHeight;
  clicks.push({ x: pageX, y: pageY, relY: +(pageY / docHeight).toFixed(3) });
  console.log(clicks.at(-1));
};

document.addEventListener('click', onClick);

// Später wieder abmelden
setTimeout(() => document.removeEventListener('click', onClick), 60_000);

{ x: 312, y: 1850, relY: 0.463 }

Position relativ zu einem Element berechnen

const box = document.querySelector('.canvas-wrapper');

box.addEventListener('pointerdown', (event) => {
  const rect = box.getBoundingClientRect();
  // Dokument-Position des Elements = Viewport-Position + Scrollversatz
  const boxTop = rect.top + window.scrollY;
  const yInBox = event.pageY - boxTop;
  console.log(`Y im Element: ${Math.round(yInBox)} px`);
});

Y im Element: 87 px

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen wie event.pageY = 10 werden ignoriert, im Strict Mode kommt es zu keinem Fehler, weil nur ein Getter existiert. Für eigene Werte gibt man clientY im Konstruktor new MouseEvent('click', { clientY: 100 }) an, woraus der Browser pageY berechnet.
Gleitkommawerte: Moderne Browser liefern bei Zoom oder hochauflösenden Displays Werte mit Nachkommastellen. Für Pixelvergleiche Math.round() nutzen.
Verschachtelte Scrollcontainer: pageY berücksichtigt nur das Scrollen des Dokuments, nicht das Scrollen innerer Elemente mit overflow: auto. Dort muss man element.scrollTop selbst einrechnen.
Fixierte Elemente: Für position: fixed ist clientY zu verwenden, sonst verrutscht das Element beim Scrollen.
Transformierte Eltern: Hat ein Vorfahr transform, einen position-Wert ungleich static oder ist er absolut positioniert, verschiebt sich der Bezugspunkt für top. pageY passt dann nicht mehr direkt.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Sehr alte IE-Versionen (vor IE9) kannten pageY nicht, dort war clientY + document.documentElement.scrollTop nötig.

Siehe auch

MouseEvent.pageX MouseEvent.clientY MouseEvent.screenY MouseEvent.offsetY Window.scrollY Element.getBoundingClientRect() MouseEvent