Event.stopPropagation() — Methode · JavaScript-Referenz

Signatur

Event.prototype.stopPropagation()

Beschreibung

Ein DOM-Ereignis durchläuft drei Phasen: In der Capturing-Phase wandert es vom window hinunter zum Zielelement, in der Target-Phase erreicht es das Ziel, und in der Bubbling-Phase steigt es wieder nach oben. stopPropagation() bricht diesen Weg ab: Nach dem aktuellen Element erhalten keine weiteren Knoten das Ereignis mehr.

Wichtig: Andere Listener, die am selben Element registriert sind, werden trotzdem noch ausgeführt. Sollen auch diese unterdrückt werden, verwendet man stopImmediatePropagation(). Außerdem verhindert stopPropagation() nicht die Standardaktion des Browsers (z. B. das Folgen eines Links oder das Absenden eines Formulars) – dafür ist preventDefault() zuständig.

Typische Anwendungsfälle sind verschachtelte klickbare Elemente (etwa ein Löschen-Button in einer klickbaren Listenzeile), Dropdowns und Modale, die sich bei einem Klick außerhalb schließen sollen, sowie das gezielte Abfangen von Ereignissen in der Capturing-Phase, bevor Kindelemente sie verarbeiten.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Löschen-Button in klickbarer Listenzeile

// HTML: <li class="row">Eintrag <button class="delete">×</button></li>
const row = document.querySelector('.row');
const deleteBtn = row.querySelector('.delete');

row.addEventListener('click', () => {
  console.log('Detailansicht öffnen');
});

deleteBtn.addEventListener('click', (event) => {
  event.stopPropagation(); // Klick erreicht die Zeile nicht
  console.log('Eintrag löschen');
});

Eintrag löschen

Dropdown schließen bei Klick außerhalb

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

// Klicks innerhalb des Menüs nicht zum document durchlassen
dropdown.addEventListener('click', (event) => {
  event.stopPropagation();
});

document.addEventListener('click', () => {
  dropdown.hidden = true;
  console.log('Menü geschlossen');
});

Menü geschlossen // nur bei Klick außerhalb von #menu

Unterschied zu stopImmediatePropagation()

const btn = document.createElement('button');
document.body.append(btn);

document.body.addEventListener('click', () => console.log('body'));

btn.addEventListener('click', (e) => {
  e.stopPropagation();
  console.log('Listener 1');
});
btn.addEventListener('click', () => console.log('Listener 2'));

btn.click();

Listener 1 Listener 2

Ereignis in der Capturing-Phase abfangen

const form = document.querySelector('form');
let locked = true;

// capture: true → läuft vor den Listenern der Kindelemente
form.addEventListener('click', (event) => {
  if (locked) {
    event.stopPropagation();
    console.log('Formular gesperrt – Klick blockiert');
  }
}, { capture: true });

Formular gesperrt – Klick blockiert

// Wichtig · Fallstricke

Keine Standardaktion unterdrückt: Links werden weiterhin geöffnet, Formulare abgeschickt. Bei Bedarf zusätzlich event.preventDefault() aufrufen.
Nur andere Knoten betroffen: Weitere Listener am selben Element laufen weiter – dafür stopImmediatePropagation() verwenden.
Bricht Event-Delegation und Drittanbieter-Code: Übermäßiger Einsatz verhindert, dass delegierte Listener (z. B. am document), Analytics-Tools oder Klick-außerhalb-Logik anderer Komponenten das Ereignis sehen. Oft ist eine Prüfung per event.target.closest() die robustere Lösung.
In Frameworks wie React (synthetische Events) wirkt stopPropagation() auf das Framework-Eventsystem; native Listener am document können je nach Version trotzdem ausgelöst werden.
Die veraltete Eigenschaft event.cancelBubble = true hat denselben Effekt, sollte aber nicht mehr genutzt werden.
Bei Ereignissen mit bubbles: false (z. B. focus) wirkt die Methode nur noch in der Capturing-Phase.
Browser-Kompatibilität: in allen modernen Browsern und seit IE9 unterstützt.

Siehe auch

Event.stopImmediatePropagation() Event.preventDefault() Event.bubbles Event.eventPhase EventTarget.addEventListener() Event.cancelBubble new RTCSessionDescription()