EventTarget.addEventListener()'s useCapture argument use?

Question

I am studying the vanilla JavaScript and I have some trouble understanding what is the use of this useCapture argument in the EventTarget.addEventListener() function.

https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

useCapture Optional

If true, useCapture indicates that the user wishes to initiate capture. After initiating capture, all events of the specified type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree. Events which are bubbling upward through the tree will not trigger a listener designated to use capture. See DOM Level 3 Events and JavaScript Event order for a detailed explanation. If not specified, useCapture defaults to false.

Reading it's doc, I've got confused from the first sentence. And trying to understand it I've setup a little test page with three nested elements, with a click listener on the two top most div.

The code :

var treeTopEl = document.getElementById('container');
var treeMiddleEl = document.getElementById('wrapper');

var output = document.getElementById('output');

var treeTopElListener = function(event){
 var elId = event.target.id;
 output.innerHTML += "\nListener on the top element was triggerd,\n\t The event target id is : "+elId; 
};

var treeMiddleElListener = function(event){
 var elId = event.target.id;
 output.innerHTML += "\nListener on the middle element was triggerd,\n\tThe event target id is : "+elId; 
};

treeTopEl.addEventListener('click', treeTopElListener, false);
treeMiddleEl.addEventListener('click', treeMiddleElListener, true);

#container, #wrapper {
  padding : 20px;
  border : 1px solid green;
}

<div id="container">
 <div id="wrapper">
   <button id="testBtn">A button</button>

 </div>
</div>
<pre id="output"></pre>

The question :

When you click the button both listeners are triggered ~~in the same order~~ no matter of the useCapture configuration : both true; both false; first one true, second one false; first one false, second one true.

What exactly captures useCapture flag ?

T.J. Crowder T.J. Crowder · Accepted Answer · 2015-06-06T14:06:42

I think this diagram from the DOM events specification pretty much says it all:

enter image description here

Basically: The useCapture argument is used to receive notification during the capture phase, rather than the bubbling phase. A capturing-phase handler will be called before any bubbling-phase handler. Note that Internet Explorer didn't support the capturing phase prior to IE9.

So a better example is two handlers on the same element, in the middle (but let's do all three levels for completeness):

hook("container", "- ");
hook("wrapper",   "&nbsp;&nbsp;- ");
hook("testBtn",   "&nbsp;&nbsp;&nbsp;&nbsp;- ");

function hook(id, prefix) {
  var element = document.getElementById(id);
  element.addEventListener("click", function(e) {
    display(id + "'s capturing handler called", prefix);
  }, true);
  element.addEventListener("click", function(e) {
    display(id + "'s bubbling called", prefix);
  }, false);
}

function display(msg, prefix) {
  var p = document.createElement('p');
  p.innerHTML = (prefix || "") + msg;
  document.body.appendChild(p);
}

#container, #wrapper {
  padding : 10px;
  border : 1px solid green;
}
p {
  font-family: sans-serif;
  padding: 0;
  margin: 0;
}

<div id="container">
 <div id="wrapper">
   <button id="testBtn">A button</button>
 </div>
</div>

EventTarget.addEventListener()'s useCapture argument use?

The question :

1 Answers