content
content copied to clipboard
mdn
"Introduction to events" article contains inaccurate/misleading statements
MDN URL
https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events
What specific section or headline is this issue about?
What information was incorrect, unhelpful, or incomplete?
The high-level introduction to events in JavaScript contains some inaccurate statements that may confuse readers.
In the capturing phase: The browser checks to see if the element's outer-most ancestor () has a click event handler registered on it for the capturing phase, and runs it if so. Then it moves on to the next element inside and does the same thing, then the next one, and so on until it reaches the direct parent of the element that was actually clicked.
In the bubbling phase, the exact opposite of the capturing phase occurs: The browser checks to see if the direct parent of the clicked element has a click event handler registered on it for the bubbling phase, and runs it if so. Then it moves on to the next immediate ancestor element and does the same thing, then the next one, and so on until it reaches the element.
While it's true that all events proceed through both the capturing and bubbling phases, the event handlers are not guaranteed to run during both stages. The way that this section is phrased implies that all event handlers run twice: once during the capturing phase (top-down) and once again on the way back up. These sections also specifically discuss click event handlers when this should apply to all events.
The docs only clarify this point in the following paragraph:
In modern browsers, by default, all event handlers are registered for the bubbling phase. So in our current example, when you click the video, the event bubbles from the
It would be helpful to link to the Event.stopPropagation docs and rewrite this section to clarify how capturing/bubbling works more generally, specifically mentioning the third argument for addEventListener since it's what determines when the ancestor event handlers run: on the way down or on the way up.
There's also an issue in the following paragraph from the section titled Fixing the problem with stopPropagation():
As we saw in the video example, this can be a very annoying behavior, but there is a way to prevent it! The standard Event object has a function available on it called stopPropagation() which, when invoked on a handler's event object, makes it so that the first handler is run but the event doesn't bubble any further up the chain, so no more handlers will be run.
This is misleading because it suggests that stopPropagation only prevents bubbling. In reality, it can also prevent propagation to event handlers further down the tree in the capturing phase, depending on whether useCapture is true. The docs on Event.stopPropagation() clarify this, but it would be helpful to clarify it here as well since this is an introductory article.
What did you expect to see?
See notes above
Do you have any supporting links, references, or citations?
The following MDN articles:
- https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
- https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation
Do you have anything more you want to share?
Upon feedback/approval, I'd be happy to rewrite these sections. But I think the article may need a broader rewrite and perhaps new code samples (some of them, like the ones that involve clicking divs, are inaccessible to keyboard users—this may need to be filed as a separate issue).
Upon feedback/approval, I'd be happy to rewrite these sections.
👍 A rewrite along the lines described in the question would be great. I’m going ahead and assigning the issue to you.
@sideshowbarker Sounds good! What is the process for incrementally merging doc updates? I don't want to push one big PR, so ideally I'd like to have my changes go to a feature branch rather than deploying immediately. Is there a way to request that a branch be created?
What is the process for incrementally merging doc updates? I don't want to push one big PR, so ideally I'd like to have my changes go to a feature branch rather than deploying immediately.
That can effectively be done just by cloning the repo into a fork of your own, creating a feature branch in your fork, and then creating the PR from that feature branch. Once the PR is opened here, the system will generate rendered output from the source in that feature branch. And then you can work from that feature branch, making incremental changes — and each time you push any new changes to that branch, the system here will automatically generate updated output from it.
At any time, you can choose to mark the PR as a Draft PR — which will prevent it from getting merged prematurely, until you’re ready to have it reviewed (or re-reviewed).
Nothing will get deployed to the production site until the PR is finally merged into the main branch.
