Custom Events & EventTarget API

Also Known As

TL;DR

Explanation

CustomEvent allows any DOM element to dispatch events with arbitrary data in the detail property. EventTarget can be subclassed to create a non-DOM event emitter. Patterns: component A dispatches 'cart:updated' on document, component B listens without knowing about A. This decouples components without shared state or direct references. The EventTarget mixin also enables event-driven communication in Web Workers and custom objects. Bubbling and capture phases allow event delegation.

Common Misconception

Why It Matters

Common Mistakes

• Not setting bubbles: true when cross-component communication is needed — non-bubbling events don't propagate.
• Not removing event listeners — addEventListener without removeEventListener causes memory leaks.
• Dispatching events before the target element exists in the DOM.
• Using string event names without a naming convention — namespace with colon: 'cart:updated', 'user:login'.

Code Examples

// Tight coupling — direct function calls:
class Cart {
    update(items) {
        this.items = items;
        checkout.refresh();   // Direct reference — Cart knows about Checkout
        analytics.track();    // Cart knows about Analytics
        header.updateBadge(); // Cart knows about Header
    }
}

// Decoupled via custom events:
class Cart {
    update(items) {
        this.items = items;
        document.dispatchEvent(new CustomEvent('cart:updated', {
            bubbles: true,
            detail: { items, count: items.length }
        }));
        // Cart knows nothing about who listens
    }
}

// Independent listeners:
document.addEventListener('cart:updated', e => checkout.refresh(e.detail));
document.addEventListener('cart:updated', e => analytics.track(e.detail));
document.addEventListener('cart:updated', e => header.updateBadge(e.detail.count));

References

• ↗ https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent

Tags

Related Terms