Event.stopImmediatePropagation() — Methode · JavaScript-Referenz

Signatur

Event.prototype.stopImmediatePropagation()

Beschreibung

stopImmediatePropagation() beendet die Verarbeitung eines Ereignisses sofort. Sind an einem Element mehrere Listener für denselben Ereignistyp registriert, werden sie normalerweise in der Reihenfolge ihrer Registrierung aufgerufen. Ruft einer davon stopImmediatePropagation() auf, werden die danach folgenden Listener an diesem Element nicht mehr ausgeführt. Außerdem wird das Ereignis nicht an andere Elemente weitergegeben, weder in der Capture- noch in der Bubbling-Phase.

Darin unterscheidet sich die Methode von stopPropagation(). Diese verhindert nur die Weitergabe an übergeordnete bzw. untergeordnete Elemente. Alle übrigen Listener am aktuellen Element laufen trotzdem noch.

Typische Einsatzfälle:

Ein Validierungs-Listener soll andere Klick-Handler blockieren, die Drittbibliotheken registriert haben.
Ein „Wächter“-Listener wird als Erster registriert und unterbindet gezielt die weitere Verarbeitung, zum Beispiel bei deaktivierten Schaltflächen oder doppelten Klicks.
Die weitere Verarbeitung soll nach einem bestimmten Listener enden.

Die Methode verhindert nicht die Standardaktion des Browsers, etwa das Absenden eines Formulars oder das Öffnen eines Links. Dafür brauchst du zusätzlich preventDefault().

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Weitere Listener am selben Element blockieren

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

button.addEventListener('click', (event) => {
  console.log('Listener 1');
  event.stopImmediatePropagation();
});

button.addEventListener('click', () => {
  console.log('Listener 2'); // wird nicht ausgeführt
});

document.body.addEventListener('click', () => {
  console.log('body-Listener'); // wird auch nicht ausgeführt
});

button.click();

Listener 1

Vergleich mit stopPropagation()

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

btn.addEventListener('click', (e) => {
  console.log('A');
  e.stopPropagation(); // stoppt nur die Weitergabe an Elternelemente
});
btn.addEventListener('click', () => console.log('B')); // läuft trotzdem
document.body.addEventListener('click', () => console.log('body'));

btn.click();

A B

Wächter-Listener gegen Doppelklicks beim Absenden

const submit = document.createElement('button');
submit.textContent = 'Bestellen';
document.body.append(submit);

let laeuft = false;

// Wächter zuerst registrieren, damit er vor allen anderen läuft
submit.addEventListener('click', (event) => {
  if (laeuft) {
    event.preventDefault();
    event.stopImmediatePropagation();
    console.log('Anfrage läuft bereits – Klick ignoriert');
    return;
  }
  laeuft = true;
  setTimeout(() => { laeuft = false; }, 2000);
});

// z. B. von einer Bibliothek registrierter Handler
submit.addEventListener('click', () => console.log('Bestellung wird gesendet'));

submit.click();
submit.click();

Bestellung wird gesendet Anfrage läuft bereits – Klick ignoriert

Mit eigenen Ereignissen an einem EventTarget

const bus = new EventTarget();

bus.addEventListener('speichern', (e) => {
  if (!e.detail.gueltig) {
    console.log('Ungültig – Verarbeitung abgebrochen');
    e.stopImmediatePropagation();
  }
});
bus.addEventListener('speichern', () => console.log('Gespeichert'));

bus.dispatchEvent(new CustomEvent('speichern', { detail: { gueltig: false } }));
bus.dispatchEvent(new CustomEvent('speichern', { detail: { gueltig: true } }));

Ungültig – Verarbeitung abgebrochen Gespeichert

// Wichtig · Fallstricke

Reihenfolge ist entscheidend: Die Methode wirkt nur auf Listener, die nach dem aufrufenden Listener an der Reihe sind. Listener, die bereits gelaufen sind, lassen sich nicht rückgängig machen. Ein blockierender Wächter muss deshalb zuerst registriert werden. Alternativ registrierst du ihn in der Capture-Phase an einem Vorfahren ({ capture: true }).
Keine Standardaktion verhindert: Links, Formularversand usw. werden weiterhin ausgeführt. Dafür kombinierst du die Methode mit event.preventDefault().
Inline- und Property-Handler zählen mit: Handler, die per onclick gesetzt wurden, reihen sich an der Stelle ihrer ersten Zuweisung in die Listener-Liste ein. Je nach Reihenfolge werden auch sie übersprungen.
Nebenwirkungen: Wenn du Ereignisse global stoppst, können Analyse-Skripte, Bibliotheken zur Barrierefreiheit oder Frameworks, die auf document lauschen (z. B. Ereignis-Delegation in React), die Ereignisse nicht mehr empfangen. Setze die Methode daher sparsam und gezielt ein.
Die Methode ist auch in Node.js verfügbar (EventTarget/Event seit Node.js 15). In allen modernen Browsern wird sie vollständig unterstützt. Bei jQuery-Ereignissen gibt es eine gleichnamige, eigene Methode auf dem jQuery-Ereignisobjekt.

Siehe auch

Event.stopPropagation() Event.preventDefault() EventTarget.addEventListener() Event.eventPhase Event.cancelBubble Event