Custom Events and EventTarget

## What CustomEvent is for The DOM event system was designed for events the browser generates: `click`, `input`, `submit`. Each of those has a specialised interface (`MouseEvent`, `InputEvent`, `SubmitEvent`) with typed properties. When *your* code wants to announce something — a cart item was added, a dialog was confirmed, a widget finished loading — there is no browser-defined interface for it. `CustomEvent` fills that gap: it is `Event` plus exactly one extra, application-owned property called `detail`. ## The constructor shape ```js const ev = new CustomEvent('cart:add', { detail: { id: 42, qty: 2 }, // your payload, default null bubbles: false, // default false cancelable: false, // default false composed: false // default false }); cartButton.dispatchEvent(ev); ``` The first argument is the event *type* — an arbitrary string. There is no registry of valid names; picking a namespaced name such as `cart:add` or `my-widget:ready` keeps you from colliding with a real DOM event name like `change`. The second argument is the init dictionary. `detail` is the only member `CustomEvent` adds; the rest come from `EventInit` and are shared with plain `Event`. ## Reading it in a listener ```js cartButton.addEventListener('cart:add', (event) => { console.log(event.type); // 'cart:add' console.log(event.detail.id); // 42 console.log(event.target); // cartButton }); ``` A listener receives the same event object the dispatcher constructed, so `event.detail` is the *same reference* — not a copy. Two consequences follow. First, there is no serialisation cost and no structured-clone restriction: you can put a function, a DOM node, a class instance, anything, in `detail`. Second, if one listener mutates `event.detail`, every later listener sees the mutation. That is occasionally useful as a deliberate collect-results channel, but as an accident it is a nasty coupling bug. ## detail is read-only `detail` is exposed as a getter on `CustomEvent.prototype`. Constructing an event and then assigning `ev.detail = {...}` does not work — in strict mode (which all ES modules are) it throws a `TypeError`, and in sloppy mode it silently does nothing. Whatever you want listeners to see must go into the init dictionary. ## Event versus CustomEvent `new Event('ready')` is entirely legitimate when the fact that the event happened *is* the whole message. `Event`'s init dictionary has no `detail` member, and passing one is simply ignored, which is a common source of an undefined-payload bug: ```js el.dispatchEvent(new Event('ready', { detail: 1 })); el.addEventListener('ready', e => console.log(e.detail)); // undefined ``` So: no payload → `Event`; payload → `CustomEvent`. ## Can I just set my own property? Event instances are ordinary JavaScript objects, so `ev.payload = data` does work. It is still worth avoiding. `detail` is the documented, tool-known slot: TypeScript's `CustomEvent<T>` types it, framework wrappers forward it, and any other developer reading the dispatch site knows immediately where to look. An ad-hoc expando is invisible to all of that. ## The legacy API Older code creates events with `document.createEvent('CustomEvent')` followed by `initCustomEvent(type, bubbles, cancelable, detail)`. Both are deprecated in the DOM standard but still implemented for compatibility. The only reason to recognise them is to read old code; write the constructor form. ## A practical shape A reusable helper keeps dispatch sites honest: ```js function emit(el, type, detail) { return el.dispatchEvent(new CustomEvent(type, { detail, bubbles: true })); } ``` That one line fixes the naming convention, guarantees `detail` is always populated, and makes the bubbling decision explicit in one place instead of at fifty call sites.