Signatur
Beschreibung
detail ist der Weg, über ein eigenes Ereignis beliebige Daten zu transportieren. Beim Erzeugen mit new CustomEvent(type, { detail }) legen Sie einen Wert fest. Jeder Listener kann ihn dann über event.detail auslesen. Erlaubt ist jeder JavaScript-Wert: primitive Werte, Objekte, Arrays, Funktionen oder sogar Promises.
Typische Einsatzgebiete sind die lose gekoppelte Kommunikation zwischen Komponenten, etwa wenn ein Web Component seinem Umfeld eine Auswahl, einen Zustandswechsel oder ein Formularergebnis mitteilt. Ein einfacher Event-Bus auf Basis von EventTarget gehört ebenfalls dazu. So ersparen Sie sich eigene Callback-Registrierungen und nutzen das vorhandene DOM-Ereignismodell mit bubbles, composed und cancelable.
Die Eigenschaft ist schreibgeschützt: Eine Zuweisung an event.detail wird ignoriert und wirft im Strict Mode einen TypeError. Sie ersetzt nur den Verweis nicht. Ist detail ein Objekt, bleibt dieses Objekt selbst veränderbar. Listener können darüber also Daten an den Auslöser zurückgeben. Wird kein detail angegeben, ist der Wert null.
Rückgabewert
detail übergeben wurde. Ohne Angabe ist er null.Beispiele
Daten mit einem eigenen Ereignis senden und empfangen
const button = document.createElement('button');
document.body.append(button);
button.addEventListener('warenkorb:hinzugefuegt', (event) => {
const { produktId, menge } = event.detail;
console.log(`Produkt ${produktId} x${menge} hinzugefügt`);
});
button.dispatchEvent(new CustomEvent('warenkorb:hinzugefuegt', {
detail: { produktId: 'A-42', menge: 3 },
bubbles: true
}));Web Component meldet eine Auswahl nach außen
class FarbWaehler extends HTMLElement {
connectedCallback() {
this.innerHTML = '<button data-farbe="rot">Rot</button><button data-farbe="blau">Blau</button>';
this.addEventListener('click', (e) => {
const farbe = e.target.dataset.farbe;
if (!farbe) return;
this.dispatchEvent(new CustomEvent('farbe-gewaehlt', {
detail: { farbe },
bubbles: true,
composed: true // verlässt auch das Shadow DOM
}));
});
}
}
customElements.define('farb-waehler', FarbWaehler);
document.addEventListener('farbe-gewaehlt', (e) => {
console.log('Gewählt:', e.detail.farbe);
});
const el = document.createElement('farb-waehler');
document.body.append(el);
el.querySelector('[data-farbe="blau"]').click();Schreibschutz und Standardwert null
'use strict';
const leer = new CustomEvent('ping');
console.log(leer.detail);
const ev = new CustomEvent('ping', { detail: { antworten: [] } });
try {
ev.detail = 'neu';
} catch (err) {
console.log(err.name);
}
// Das Objekt selbst bleibt veränderbar, z. B. für Rückmeldungen
const ziel = new EventTarget();
ziel.addEventListener('ping', (e) => e.detail.antworten.push('pong'));
ziel.dispatchEvent(ev);
console.log(ev.detail.antworten);// Wichtig · Fallstricke
- Nur lesbar:
event.detail = …ist ohne Wirkung und wirft im Strict Mode einenTypeError. Die Daten legen Sie ausschließlich im Konstruktor fest (oder über das veralteteinitCustomEvent()). - Kein Klonen:
detailwird per Verweis weitergegeben. Alle Listener teilen sich dasselbe Objekt. Unbeabsichtigte Änderungen können Sie mitObject.freeze()oder einer Kopie verhindern. - Kein Transport über Kontextgrenzen: Anders als bei
postMessagegelangtdetailnicht über Worker oder Fenster hinweg. Es funktioniert nur innerhalb desselben JavaScript-Kontexts. - Browser-Erweiterungen: Content-Scripts in Firefox sehen Objekte aus der Seite unter Umständen nur als eingeschränkte Wrapper. Übergeben Sie dort eher primitive Werte oder JSON-Strings.
- Kompatibilität: Alle modernen Browser unterstützen die Eigenschaft. In Node.js ist
CustomEventab Version 19 global verfügbar (experimentell seit 18.7). - Sicherheit: Andere Skripte auf der Seite können Ereignisse mit beliebigem
detailauslösen. Prüfen Sie die Daten deshalb, bevor Sie sie z. B. perinnerHTMLin das DOM schreiben (XSS).