MouseEvent.pageX — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.pageX

Beschreibung

Die schreibgeschützte Eigenschaft pageX gibt an, an welcher horizontalen Position (in CSS-Pixeln) sich der Mauszeiger beim Auslösen des Events befand, und zwar gemessen von der linken Kante des gesamten Dokuments. Anders als bei clientX wird ein horizontaler Scroll-Versatz mitgezählt: pageX entspricht damit clientX + window.scrollX (Stand der Spezifikation: clientX plus Scroll-Offset des Viewports).

Die Eigenschaft eignet sich immer dann, wenn Elemente absolut im Dokument positioniert werden sollen, etwa Tooltips, Kontextmenüs oder Markierungen, die mit der Seite mitscrollen. Möchtest du dagegen etwas mit position: fixed am Viewport ausrichten, nimm clientX. Für Koordinaten innerhalb eines bestimmten Elements eignet sich offsetX oder die Berechnung über getBoundingClientRect().

Seit CSSOM View ist pageX als double definiert. Bei Zoom oder hochauflösenden Bildschirmen können deshalb Nachkommastellen auftauchen. Da PointerEvent und DragEvent von MouseEvent erben, steht pageX auch dort zur Verfügung. Bei TouchEvent findest du den Wert dagegen am einzelnen Touch-Objekt.

Rückgabewert

Typ

number

Beschreibung

Horizontale Position in CSS-Pixeln relativ zur linken Dokumentkante, inklusive Scroll-Versatz. Kann Nachkommastellen haben. Bei synthetischen Events ohne Koordinaten ist der Wert 0.

Beispiele

Klickposition im Dokument protokollieren

document.addEventListener('click', (event) => {
  console.log(`pageX: ${event.pageX}, clientX: ${event.clientX}, scrollX: ${window.scrollX}`);
});

pageX: 1320, clientX: 520, scrollX: 800

Tooltip absolut am Mauszeiger positionieren

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

const ziel = document.querySelector('#hilfe');

ziel.addEventListener('mousemove', (event) => {
  // position:absolute bezieht sich hier auf das Dokument, daher pageX/pageY
  tooltip.style.left = `${event.pageX + 12}px`;
  tooltip.style.top = `${event.pageY + 12}px`;
  tooltip.style.display = 'block';
});

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

Position relativ zu einem Element berechnen

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

box.addEventListener('pointerdown', (event) => {
  const rect = box.getBoundingClientRect();
  // Linke Kante des Elements in Dokumentkoordinaten
  const elementLeft = rect.left + window.scrollX;
  const x = event.pageX - elementLeft;
  console.log(`Klick bei x = ${Math.round(x)} px innerhalb der Box`);
});

Klick bei x = 143 px innerhalb der Box

Synthetisches Event mit Koordinaten

const evt = new MouseEvent('click', { clientX: 100, bubbles: true });
document.body.addEventListener('click', (e) => console.log(e.pageX), { once: true });
document.body.dispatchEvent(evt);

100 (zzgl. aktuellem window.scrollX)

// Wichtig · Fallstricke

Verwechslungsgefahr: pageX bezieht sich auf das Dokument, clientX auf den Viewport, screenX auf den Bildschirm und offsetX auf den Padding-Rand des Zielelements. Wenn Werte beim Scrollen „springen“, ist meist die falsche Eigenschaft im Einsatz.
Schreibgeschützt: Eine Zuweisung wie event.pageX = 10 wird stillschweigend ignoriert. Im Strict Mode wird ein TypeError geworfen. Bei synthetischen Events legst du die Werte über clientX im Konstruktor fest, pageX wird daraus abgeleitet.
Nachkommastellen: Moderne Browser geben einen double zurück. Runde bei Bedarf mit Math.round(), bevor du Werte vergleichst.
CSS-Transformationen und iframes: pageX berücksichtigt keine transform-Angaben am Zielelement und bezieht sich immer auf das Dokument, in dem das Event ausgelöst wird, nicht auf das übergeordnete Fenster.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Nur sehr alte IE-Versionen (≤ 8) kannten pageX nicht, dort musste man mit clientX + document.documentElement.scrollLeft rechnen.
Performance: mousemove feuert sehr häufig. Bündle DOM-Updates, die auf pageX beruhen, am besten mit requestAnimationFrame.

Siehe auch

MouseEvent MouseEvent.pageY MouseEvent.clientX MouseEvent.screenX MouseEvent.offsetX Window.scrollX Element.getBoundingClientRect() PointerEvent