MouseEvent.relatedTarget — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.relatedTarget

Beschreibung

relatedTarget ergänzt event.target bei Ereignissen, bei denen der Mauszeiger von einem Element zu einem anderen wechselt. Damit sieht man nicht nur, wo das Ereignis stattfindet, sondern auch, woher der Zeiger kommt oder wohin er geht.

Welches Element gemeint ist, hängt vom Ereignistyp ab:

mouseover / mouseenter: target ist das Element, das betreten wird, relatedTarget das Element, das der Zeiger verlassen hat.
mouseout / mouseleave: target ist das Element, das verlassen wird, relatedTarget das Element, das der Zeiger jetzt betritt.
dragenter: relatedTarget ist das Element, das der Zeiger beim Ziehen verlassen hat.
dragleave: relatedTarget ist das Element, das der Zeiger beim Ziehen betritt.

Bei allen anderen Mausereignissen (etwa click, mousedown, mousemove) ist der Wert null. Besonders nützlich ist die Eigenschaft, um bei mouseover/mouseout zu unterscheiden, ob der Zeiger ein Element wirklich verlässt oder nur in eines seiner Kindelemente wechselt. So lassen sich Tooltips, Dropdown-Menüs und Hover-Effekte ohne Flackern umsetzen.

Rückgabewert

Typ

EventTarget | null

Beschreibung

Das sekundäre Ziel des Ereignisses (meist ein Element) oder null, wenn es keines gibt – etwa wenn der Zeiger von außerhalb des Fensters kommt bzw. das Fenster verlässt.

Beispiele

Übergänge protokollieren: woher kommt, wohin geht die Maus?

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

const describe = (el) => el ? `<${el.tagName.toLowerCase()}${el.id ? '#' + el.id : ''}>` : 'außerhalb des Fensters';

box.addEventListener('mouseover', (event) => {
  console.log(`Betreten: ${describe(event.target)} – kommt von ${describe(event.relatedTarget)}`);
});

box.addEventListener('mouseout', (event) => {
  console.log(`Verlassen: ${describe(event.target)} – geht nach ${describe(event.relatedTarget)}`);
});

Betreten: <div#box> – kommt von <body> Verlassen: <div#box> – geht nach <span#label>

Dropdown-Menü schließen, nur wenn die Maus es wirklich verlässt

const menu = document.querySelector('.dropdown');

const onMouseOut = (event) => {
  // Wechsel in ein Kindelement? Dann nicht schließen.
  if (event.relatedTarget && menu.contains(event.relatedTarget)) {
    return;
  }
  menu.classList.remove('open');
  console.log('Menü geschlossen');
};

menu.addEventListener('mouseout', onMouseOut);

// Später, z. B. beim Abbau der Komponente:
// menu.removeEventListener('mouseout', onMouseOut);

Menü geschlossen

Synthetisches Ereignis mit relatedTarget erzeugen (z. B. in Tests)

const source = document.createElement('div');
const dest = document.createElement('div');
document.body.append(source, dest);

dest.addEventListener('mouseover', (event) => {
  console.log(event.relatedTarget === source);
});

const event = new MouseEvent('mouseover', {
  bubbles: true,
  relatedTarget: source
});

dest.dispatchEvent(event);

true

Ziehen über eine Drop-Zone ohne Flackern

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

zone.addEventListener('dragenter', () => zone.classList.add('active'));

zone.addEventListener('dragleave', (event) => {
  // Nur entfernen, wenn der Zeiger die Zone tatsächlich verlässt
  if (!zone.contains(event.relatedTarget)) {
    zone.classList.remove('active');
  }
});

zone.addEventListener('dragover', (event) => event.preventDefault());

// Wichtig · Fallstricke

Immer auf null prüfen: Kommt der Zeiger von außerhalb des Browserfensters oder verlässt er es, ist relatedTarget null. Ein ungeprüfter Aufruf wie event.relatedTarget.closest() wirft dann einen TypeError. Node.contains(null) liefert dagegen gefahrlos false.
Entfernte Elemente: Wird das Element unter dem Zeiger aus dem DOM entfernt, kann relatedTarget auf einen nicht mehr eingehängten Knoten zeigen oder null sein. Das verhält sich nicht in allen Browsern gleich.
Shadow DOM: Wie target wird auch relatedTarget an Shadow-Grenzen umgeleitet (Retargeting). Außerhalb einer Web-Komponente sieht man das Host-Element, nicht den inneren Knoten. Liegen target und relatedTarget nach dem Umleiten auf demselben Knoten, wird das Ereignis außerhalb der Shadow-Grenze gar nicht ausgelöst.
mouseenter/mouseleave statt mouseover/mouseout: Diese Ereignisse steigen nicht auf (kein Bubbling) und werden beim Wechsel in Kindelemente nicht ausgelöst. Oft ersparen sie die manuelle Prüfung mit contains().
Nur lesbar: Die Eigenschaft lässt sich nicht nachträglich ändern. Bei synthetischen Ereignissen setzt man sie über das Options-Wörterbuch von new MouseEvent().
Die analoge Eigenschaft für Fokus-Wechsel ist FocusEvent.relatedTarget (bei focus, blur, focusin, focusout). Weil PointerEvent von MouseEvent erbt, gilt relatedTarget auch für pointerover/pointerout.
Die Eigenschaft wird von allen gängigen Browsern unterstützt. Das alte Internet Explorer-Pendant fromElement/toElement ist veraltet.

Siehe auch

MouseEvent Event.target FocusEvent.relatedTarget Node.prototype.contains() MouseEvent.layerX