CKTIS / JavaScript
Event.target and capture listeners
Tell the event’s target apart from the object running the listener, and see how the `capture` option changes listener order in the DOM.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
event.target
event.currentTarget
event.eventPhase
node.addEventListener(type, listener, { capture: true })
node.addEventListener(type, listener, true)
node.addEventListener(type, listener)Event.target and capture listener phase describe two different things. event.target identifies the event target as seen by the listener; event.currentTarget identifies the object on which the running listener was registered. Both properties are read-only. Outside a listener, currentTarget is null, so save the object during the call if you need it later.
In an ordinary DOM tree, the event first travels through the ancestors toward the target. During this phase (Event.CAPTURING_PHASE, 1), listeners run if registered with { capture: true } or with true as the third argument to addEventListener(). The capture option defaults to false.
On the target itself, capture listeners run before non-capture listeners, but both groups see the same event.eventPhase: Event.AT_TARGET (2). Then, only if event.bubbles is true, the event travels back through the ancestors in reverse order (Event.BUBBLING_PHASE, 3), running their non-capture listeners. Turning off bubbling does not disable capture or at-target handling.
These are DOM APIs, not ECMAScript features. In an ordinary tree, target stays the same during propagation, but across a shadow DOM boundary it can refer to the host instead of the internal node.
Examples
(() => {
// Node.js has no DOM tree. This fallback models only the propagation used here.
class DemoNode {
#parent = null;
#listeners = [];
append(child) {
child.#parent = this;
}
addEventListener(type, listener, options) {
const capture = options === true || options?.capture === true;
this.#listeners.push({ type, listener, capture });
}
dispatchEvent(event) {
const ancestors = [];
for (let node = this.#parent; node !== null; node = node.#parent) {
ancestors.push(node);
}
let currentTarget = null;
let phase = Event.NONE;
Object.defineProperties(event, {
target: { configurable: true, get: () => this },
currentTarget: { configurable: true, get: () => currentTarget },
eventPhase: { configurable: true, get: () => phase }
});
const invoke = (node, nextPhase, capture) => {
currentTarget = node;
phase = nextPhase;
for (const entry of node.#listeners.slice()) {
if (entry.type === event.type && entry.capture === capture) {
entry.listener.call(node, event);
}
}
};
try {
for (let i = ancestors.length - 1; i >= 0; i--) {
invoke(ancestors[i], Event.CAPTURING_PHASE, true);
}
invoke(this, Event.AT_TARGET, true);
invoke(this, Event.AT_TARGET, false);
if (event.bubbles) {
for (const node of ancestors) {
invoke(node, Event.BUBBLING_PHASE, false);
}
}
} finally {
currentTarget = null;
phase = Event.NONE;
}
return !event.defaultPrevented;
}
}
const createElement = (tag) =>
typeof document === 'undefined' ? new DemoNode() : document.createElement(tag);
const parent = createElement('div');
const child = createElement('button');
parent.id = 'parent';
child.id = 'child';
parent.append(child);
const report = (label) => (event) => {
console.log(`${label}: target=${event.target.id}, currentTarget=${event.currentTarget.id}, phase=${event.eventPhase}`);
};
parent.addEventListener('demo', report('parent bubble'));
child.addEventListener('demo', report('child non-capture'));
parent.addEventListener('demo', report('parent capture'), { capture: true });
child.addEventListener('demo', report('child capture'), { capture: true });
child.dispatchEvent(new Event('demo', { bubbles: true }));
})();Result
parent capture: target=child, currentTarget=parent, phase=1 child capture: target=child, currentTarget=child, phase=2 child non-capture: target=child, currentTarget=child, phase=2 parent bubble: target=child, currentTarget=parent, phase=3
Run the snippet in a browser console. The elements stay detached from the document, and `dispatchEvent()` calls the listeners synchronously. In Node.js, the snippet uses a small propagation model instead of the browser DOM. Change `bubbles` to `false` and only the final line disappears.
Related lessons
- JavaScript · Lesson 40 · Intermediate · Version: 3