Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

CustomEvent: passing data with detail and bubbling with bubbles

Use `detail` to carry data in a custom event and `bubbles` to let non-capturing listeners on ancestors receive it after the target phase.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

new CustomEvent(type)
new CustomEvent(type, { detail: payload, bubbles: true })
event.detail
event.bubbles
target.dispatchEvent(event)

new CustomEvent(type, options) creates a DOM event. type is a case-sensitive event name, and options is optional. Creating the event does not dispatch it: call target.dispatchEvent(event) to invoke the applicable listeners synchronously before the call returns.

CustomEvent.detail/bubbles refers to two independent settings. detail carries the payload and defaults to null. Listeners read it through the read-only event.detail property. You can pass a primitive or an object. An object is neither cloned nor frozen: listeners receive the same object and can change its mutable properties.

The bubbles option defaults to false. Setting bubbles: true enables the bubble phase: after the target phase, the event can reach listeners on ancestors unless propagation has been stopped. The read-only event.bubbles property is inherited from Event. A value of false does not disable listeners on the target or capturing listeners (capture: true) on ancestors.

stopPropagation() stops further propagation; cancelable separately controls whether preventDefault() can cancel the event. To let an event dispatched inside a shadow tree bubble outside it, also set composed: true (default false). A script-dispatched event has isTrusted set to false; do not treat it as proof of user action. CustomEvent is a DOM API, not part of ECMAScript 2024. Availability depends on the runtime.

Examples

{
  const hasDOM = typeof document !== "undefined";
  const parent = hasDOM ? document.createElement("div") : new EventTarget();
  const child = hasDOM ? document.createElement("div") : new EventTarget();
  if (hasDOM) parent.appendChild(child);

  const type = "score-change";
  const lines = [];
  child.addEventListener(type, (event) => {
    lines.push(`child: ${event.detail.score}, bubbles=${event.bubbles}`);
  });
  parent.addEventListener(type, (event) => {
    lines.push(`parent: ${event.detail.score}, bubbles=${event.bubbles}`);
  });

  function dispatchFromChild(event) {
    child.dispatchEvent(event);
    // Without a DOM tree, model just the bubbling step to one parent.
    if (!hasDOM && event.bubbles && !event.cancelBubble) {
      parent.dispatchEvent(event);
    }
  }

  dispatchFromChild(new CustomEvent(type, { detail: { score: 1 } }));
  dispatchFromChild(new CustomEvent(type, {
    detail: { score: 2 },
    bubbles: true,
  }));

  console.log(lines.join("\n"));
}

Result

child: 1, bubbles=false
child: 2, bubbles=true
parent: 2, bubbles=true

Run the block in Node.js 24 or a browser console. In a browser, the elements are detached from the document, but `child` still has a parent and native DOM bubbling applies. In Node.js, the code explicitly forwards the event to `parent` to model that one bubbling step. In both runtimes, `child` receives both events; the non-capturing listener on `parent` receives only the second one, with `score: 2`.

Related lessons

  • JavaScript · Lesson 43 · Advanced · Version: 4

Sources