HTMLElement: dragleave — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("dragleave", handler)

Beschreibung

Das dragleave-Ereignis gehört zur HTML-Drag-and-Drop-API. Es wird auf dem Element ausgelöst, das der Mauszeiger während eines Ziehvorgangs verlässt. Das ist das Gegenstück zu dragenter. Meist nutzt man es, um eine optische Hervorhebung der Drop-Zone wieder zu entfernen, zum Beispiel eine CSS-Klasse wie .is-over.

Den Handler registriert man mit element.addEventListener("dragleave", handler) oder über die Eigenschaft element.ondragleave = handler. Das Ereignis ist ein DragEvent, es steigt im DOM auf (bubbles) und lässt sich nicht abbrechen (cancelable: false). Die Standardaktion lässt sich also nicht mit preventDefault() verhindern.

Wichtig: dragleave wird auch ausgelöst, wenn der Zeiger von der Drop-Zone auf eines ihrer Kindelemente wechselt. Gleich danach folgt dort ein dragenter. Wer das nicht berücksichtigt, bekommt eine flackernde Hervorhebung. Übliche Lösungen sind ein Zähler für dragenter/dragleave, eine Prüfung mit event.relatedTarget und contains() oder pointer-events: none auf den Kindelementen während des Ziehens.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"dragleave"`.
$handler Pflicht	(event: DragEvent) => void		Callback, der ein `DragEvent` bekommt. Wichtige Eigenschaften: `target` (das verlassene Element), `relatedTarget` (das Element, das der Zeiger betritt, oder `null`), `dataTransfer` sowie `clientX`/`clientY`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `capture`, `once`, `passive` oder `signal` (zum Entfernen über einen `AbortController`).

Beispiele

Hervorhebung der Drop-Zone entfernen

const zone = document.querySelector('#dropzone');

zone.addEventListener('dragenter', (e) => {
  e.preventDefault();
  zone.classList.add('is-over');
});

zone.addEventListener('dragover', (e) => {
  e.preventDefault(); // nötig, damit drop erlaubt ist
});

zone.addEventListener('dragleave', () => {
  zone.classList.remove('is-over');
  console.log('Drop-Zone verlassen');
});

zone.addEventListener('drop', (e) => {
  e.preventDefault();
  zone.classList.remove('is-over');
});

Drop-Zone verlassen

Flackern bei Kindelementen verhindern (relatedTarget)

const zone = document.querySelector('#dropzone');

zone.addEventListener('dragleave', (e) => {
  // Wechselt der Zeiger nur auf ein Kindelement, nichts tun
  if (e.relatedTarget && zone.contains(e.relatedTarget)) return;
  zone.classList.remove('is-over');
});

Zähler-Methode für verschachtelte Inhalte

const zone = document.querySelector('#dropzone');
let depth = 0;

zone.addEventListener('dragenter', (e) => {
  e.preventDefault();
  depth++;
  zone.classList.add('is-over');
});

zone.addEventListener('dragleave', () => {
  depth--;
  if (depth === 0) zone.classList.remove('is-over');
});

zone.addEventListener('drop', (e) => {
  e.preventDefault();
  depth = 0;
  zone.classList.remove('is-over');
});

ondragleave-Eigenschaft und Entfernen des Listeners

const zone = document.querySelector('#dropzone');

// Variante 1: on-Eigenschaft (erlaubt nur einen Handler)
zone.ondragleave = () => console.log('verlassen (on-Eigenschaft)');

// Variante 2: benannter Listener, der sich wieder entfernen lässt
const onLeave = (e) => console.log('verlassen:', e.target.id);
zone.addEventListener('dragleave', onLeave);

// Später, z. B. beim Abbau der Komponente:
zone.removeEventListener('dragleave', onLeave);
zone.ondragleave = null;

verlassen (on-Eigenschaft) verlassen: dropzone

// Wichtig · Fallstricke

Kindelemente: dragleave wird auch beim Wechsel auf ein Kindelement ausgelöst und steigt von dort zur Drop-Zone auf. Deshalb vorher event.target bzw. event.relatedTarget prüfen oder einen Zähler verwenden.
relatedTarget: Ältere Safari-Versionen haben relatedTarget bei Drag-Ereignissen teilweise als null geliefert. Die Zähler-Methode funktioniert dort zuverlässiger.
Nicht abbrechbar: preventDefault() hat bei dragleave keine Wirkung. Damit drop ausgelöst wird, muss man die Standardaktion stattdessen in dragenter und dragover verhindern.
Kein Datenzugriff: Während dragleave ist dataTransfer geschützt. getData() gibt einen leeren String zurück, nur types ist lesbar.
Nach einem erfolgreichen drop folgt kein dragleave. Aufräumen muss man deshalb auch im drop- und dragend-Handler.
Auf Touch-Geräten löst native HTML-Drag-and-Drop je nach Browser nur eingeschränkt aus. iOS Safari unterstützt es erst ab Version 15.

Siehe auch

dragenter dragover drop dragstart dragend DragEvent DataTransfer