Element: pointerleave — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("pointerleave", handler)

Beschreibung

Das Ereignis pointerleave gehört zu den Pointer Events und fasst Maus-, Stift- und Touch-Eingaben unter einer Schnittstelle zusammen. Es wird ausgelöst, sobald der Zeiger den Bereich eines Elements verlässt. Registrieren lässt es sich mit element.addEventListener("pointerleave", handler) oder über die Eigenschaft element.onpointerleave = handler. Der Handler bekommt ein PointerEvent-Objekt.

Anders als pointerout steigt pointerleave nicht im DOM auf (kein Bubbling). Das Ereignis wird auch nicht ausgelöst, wenn der Zeiger nur von einem Element auf eines seiner Kindelemente wechselt. Deshalb eignet es sich gut für Hover-Effekte, Tooltips und Dropdown-Menüs: Du bekommst genau ein Ereignis, wenn der Zeiger den ganzen Bereich wirklich verlässt, und musst nicht wie bei pointerout ständig relatedTarget prüfen.

Bei Touch- und Stift-Eingaben wird pointerleave auch ausgelöst, wenn der Kontakt endet (nach pointerup) oder abgebrochen wird (nach pointercancel), denn ein Finger „schwebt“ nicht über dem Element. Die Reihenfolge ist in der Regel pointerout → pointerleave.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"pointerleave"`.
$handler Pflicht	(event: PointerEvent) => void		Die Rückruffunktion. Sie bekommt ein `PointerEvent` mit u. a. `pointerId`, `pointerType` (`"mouse"`, `"pen"`, `"touch"`), `clientX`/`clientY` und `relatedTarget`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `passive`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignis selbst ist nicht abbrechbar (cancelable: false) und steigt nicht auf (bubbles: false).

Beispiele

Hover-Hervorhebung zurücksetzen

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

card.addEventListener('pointerenter', () => {
  card.classList.add('is-hovered');
});

card.addEventListener('pointerleave', (event) => {
  card.classList.remove('is-hovered');
  console.log(`Verlassen mit: ${event.pointerType}`);
});

Verlassen mit: mouse

Dropdown schließen – Kindelemente lösen nichts aus

const menu = document.querySelector('#menu');
const submenu = menu.querySelector('.submenu');

menu.addEventListener('pointerenter', () => submenu.hidden = false);

// Wird NICHT ausgelöst, wenn der Zeiger ins Untermenü wechselt,
// weil das Untermenü ein Nachfahre von #menu ist
menu.addEventListener('pointerleave', () => {
  submenu.hidden = true;
});

Über die on-Property setzen und wieder entfernen

const tooltipTarget = document.querySelector('[data-tooltip]');
const tooltip = document.querySelector('#tooltip');

const hideTooltip = () => {
  tooltip.hidden = true;
};

// Variante 1: on-Property
tooltipTarget.onpointerleave = hideTooltip;
// Entfernen:
tooltipTarget.onpointerleave = null;

// Variante 2: addEventListener / removeEventListener
tooltipTarget.addEventListener('pointerleave', hideTooltip);
tooltipTarget.removeEventListener('pointerleave', hideTooltip);

Zeichnung auf einem Canvas beenden, wenn der Zeiger den Bereich verlässt

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
let drawing = false;

canvas.addEventListener('pointerdown', (e) => {
  drawing = true;
  ctx.beginPath();
  ctx.moveTo(e.offsetX, e.offsetY);
});

canvas.addEventListener('pointermove', (e) => {
  if (!drawing) return;
  ctx.lineTo(e.offsetX, e.offsetY);
  ctx.stroke();
});

const stop = () => { drawing = false; };
canvas.addEventListener('pointerup', stop);
canvas.addEventListener('pointerleave', stop);

// Wichtig · Fallstricke

Kein Bubbling: Event-Delegation über ein Elternelement funktioniert bei pointerleave nicht direkt. Dafür brauchst du pointerout oder einen Listener mit { capture: true }.
Pointer Capture: Hat ein Element mit setPointerCapture() den Zeiger übernommen, wird pointerleave erst ausgelöst, wenn die Übernahme endet (lostpointercapture). Vorher bekommt das Element das Ereignis nicht, auch wenn der Zeiger den Bereich schon verlassen hat.
Touch: Auf Touchgeräten gibt es kein echtes Hovern. pointerleave kommt direkt nach pointerup oder pointercancel. Hover-Logik sollte deshalb event.pointerType berücksichtigen.
DOM-Änderungen: Wird das Element unter dem Zeiger entfernt oder verschoben, feuern Browser pointerleave nicht immer gleich. Darauf solltest du dich nicht verlassen.
Kompatibilität: Pointer Events werden in allen modernen Browsern unterstützt, in Safari ab Version 13. Für sehr alte Browser brauchst du als Ausweichlösung mouseleave bzw. Touch-Events.

Siehe auch

PointerEvent Element.setPointerCapture() Element: pointermove Element: pointerenter Element: pointerover