mdn / mdn/content

A `load` event listener/handler must "atomically" accompany its element

Open
#44,591 4 comments 0 reactions 0 assignees View on GitHub
Content:WebAPI needs triage
Dominant language
Markdown
Stars
11k
Forks
23.2k
Avg merge
2d 9h
Merged PRs (30d)
331

Description

### MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/load_event

### What specific section or headline is this issue about?

_No response_

### What information was incorrect, unhelpful, or incomplete?

The article ["Understand the critical path"](https://web.dev/learn/performance/understanding-the-critical-path) states:

> As soon as the browser gets any portion of a page's HTML, the browser starts processing it. The browser can then—and often does—decide to render it well before receiving the rest of a page's HTML.

Indeed, Chrome starts rendering HTML (and executing JS, as far as I recall) before receiving all the HTML code.

Therefore, by the time a `` starts executing that adds a `load` event handler or listener to an element that was defined outside that `<script>` tag, the element might already have been rendered and the `load` event might have occurred. In those cases, the handler/listener will never get invoked, which might violate the dev's assumptions in other code and lead to bugs. The provided example actually contains such a bug.

### What did you expect to see?

Mention this subtlety and state that an element and its `load` event handler or listener must be defined in the same HTML tag (to not get separated into different rendering stages):
- either `<img onload=`...`>`
- or a `<script>` tag within which the element is dynamically created as well as the handler/listener attached
- or a `<script>` tag (for adding the handler/listener) nested in the element's tag (unless the element is a [void element](https://developer.mozilla.org/en-US/docs/Glossary/Void_element))

Remove the bug from the example accordingly.

### Do you have any supporting links, references, or citations?

_No response_

### Do you have anything more you want to share?

_No response_

### MDN metadata

Should be https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/load_event below instead
<s>
<!-- Do not make changes below this line -->
<details>
<summary>Page report details</summary>

* Folder: `en-us/web/api/window/load_event`
* MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event
* GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/window/load_event/index.md
* Last commit: https://github.com/mdn/content/commit/09d8ff096be97b28ea415fc4c68fb1cff0ff8af9
* Document last modified: 2026-04-06T19:43:24.000Z

</details>
</s>

Contributor guide

Open the contributing guide

Research direction

Open the MDN load event article linked in the issue and inspect the documented example and its metadata path, en-us/web/api/window/load_event/index.md. Compare the example with the linked critical-path explanation and verify the claimed load-event timing before revising the explanation and example; done means the page targets HTMLElement correctly and no longer demonstrates the reported bug.

Written by the indexing model from the issue text.

Assessment

Tech stack
html, javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.