Node.js Reference ยท Globals and Console
EventTarget and Event
Reference for EventTarget, Event and CustomEvent in Node.js: addEventListener options, dispatchEvent, preventDefault, listener objects and how it differs from EventEmitter.
EventTarget is the web platform's event API, available as a global in Node.js. An object that extends it can register listeners with addEventListener() and notify them with dispatchEvent(). The thing being dispatched is an Event (or a CustomEvent that carries extra data in detail).
Node's classic EventEmitter still dominates server code, but EventTarget is what AbortSignal, MessagePort, fetch-related classes and many cross-platform libraries use. If your code should run unchanged in browsers and Node.js, prefer it.
const target = new EventTarget(); target.addEventListener('ping', () => console.log('pong')); target.dispatchEvent(new Event('ping'));
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
target.addEventListener(type, listener[, options]) target.removeEventListener(type, listener[, options]) target.dispatchEvent(event): boolean new Event(type[, { bubbles, cancelable, composed }]) new CustomEvent(type[, { detail, ...eventInit }])
| Name | Description |
|---|---|
type |
The event name, a string. |
listener |
A function, or an object with a handleEvent(event) method. |
options.once |
Remove the listener after its first call. |
options.signal |
An AbortSignal; aborting it removes the listener. |
options.capture |
Registers for the capture phase (matters only for removal in Node.js, which has no DOM tree). |
options.passive |
Hint that the listener will not call preventDefault(). |
Returns: dispatchEvent() returns false if the event is cancelable and a listener called preventDefault(), otherwise true.
Errors: dispatchEvent() throws ERR_INVALID_ARG_TYPE if the argument is not an Event. Dispatching the same event object while it is already being dispatched throws ERR_EVENT_RECURSION.
Usage notes
- Listener identity: adding the same function for the same type twice registers it once. Remove it with the same function reference (and the same
captureflag). - Exceptions in listeners do not stop other listeners or reach
dispatchEvent()'s caller. Node reports them as uncaught exceptions on a later tick. - No special
errorevent. UnlikeEventEmitter, an event namederrorwith no listener is silently fine. - Data goes in
detailforCustomEvent; a plainEventcannot carry data unless you subclass it. event.targetis set during dispatch andnullfor a fresh event.stopImmediatePropagation()prevents later listeners on the same target from running.- Listener order is registration order; return values are ignored.
- Differences from
EventEmitter: noemit()arguments (one event object instead), noprependListener, nolistenerCounton the instance (useevents.getEventListeners(target, type)), and no'newListener'events. - Awaiting an event:
events.once(target, 'type')fromnode:eventsreturns a promise, andevents.on()gives an async iterator. - Max listeners: Node warns about a possible leak when a single
EventTargethas more than 10 listeners for one type (adjustable withevents.setMaxListeners()). CustomEventbecame a stable global in Node.js 19+ (experimental flag earlier in 18).