Skip to content
Tutorials Center
My learning

Topics

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.

NODE
const target = new EventTarget();
target.addEventListener('ping', () => console.log('pong'));
target.dispatchEvent(new Event('ping'));

Try it

Node.js Listeners, once and CustomEvent

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.

Node.js Cancelable events and removal with a signal

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

NODE
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 capture flag).
  • 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 error event. Unlike EventEmitter, an event named error with no listener is silently fine.
  • Data goes in detail for CustomEvent; a plain Event cannot carry data unless you subclass it.
  • event.target is set during dispatch and null for 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: no emit() arguments (one event object instead), no prependListener, no listenerCount on the instance (use events.getEventListeners(target, type)), and no 'newListener' events.
  • Awaiting an event: events.once(target, 'type') from node:events returns a promise, and events.on() gives an async iterator.
  • Max listeners: Node warns about a possible leak when a single EventTarget has more than 10 listeners for one type (adjustable with events.setMaxListeners()).
  • CustomEvent became a stable global in Node.js 19+ (experimental flag earlier in 18).