onload
Runs JavaScript code when a resource has finished loading: the whole page, an image, a frame, a script or a stylesheet.
- Applies to
<body>,<img>,<iframe>,<script>with thesrcattribute,<link>and other elements that load a resource
Example
#<p id="status">Loading the cover…</p>
<img src="/collections/covers/kurs-html-css-od-podstaw.webp"
alt="Cover of the HTML and CSS from scratch course" width="300" height="200"
onload="
const size = this.naturalWidth + ' × ' + this.naturalHeight + ' px';
document.getElementById('status').textContent = 'Cover loaded: ' + size;
">After the image is downloaded, this.naturalWidth and this.naturalHeight give the file’s real dimensions, even though on the page the image is scaled down to 300 × 200 pixels.
Definition and usage
#The onload attribute reacts to the load event, which fires when an element has finished loading its resource. On an <img> that means the downloaded image, on an <iframe> the loaded document in the frame, on a <script src> the downloaded and executed script, and on a <link rel="stylesheet"> the ready stylesheet. When loading fails, the error event fires instead of load, which you can handle with the onerror attribute.
On the <body> element, the attribute applies to the whole page and works the same as the load event of the window object. It fires only once all images, styles, scripts and frames have loaded, so on a slow connection a lot of time can pass. If a script needs only the ready HTML, it is better to use the defer attribute or the DOMContentLoaded event, which fires earlier.
In the attribute’s code, this points to the element, for example a loaded image with its real dimensions naturalWidth and naturalHeight. The load event does not bubble up the tree, so you set the attribute directly on the element that loads the resource. In larger projects, add the handling through addEventListener("load", …).
Syntax
#<img src="…" alt="…" onload="JavaScript code">
<body onload="JavaScript code">…</body>When the load event fires
#<body>
The whole page has loaded: HTML, images, styles, scripts and frames. The same asloadon thewindowobject.<img>
The image has been downloaded. Withloading="lazy"this happens only when the image approaches the visible part of the page.<iframe>
A document has loaded in the frame. The event also fires on every subsequent navigation inside the frame.<script src>
An external script has been downloaded and executed.<link rel="stylesheet">
A stylesheet has been downloaded and processed.
More examples
#<p id="avatar-status">Loading the avatar…</p>
<img src="data:," alt="User avatar" width="64" height="64"
onload="document.getElementById('avatar-status').textContent = 'Avatar loaded'"
onerror="document.getElementById('avatar-status').textContent = 'Failed to load the avatar'">The data:, address is a deliberately broken image, so error fires instead of load. The browser shows the alternative text, and onerror changes the message.
<body onload="document.getElementById('status').textContent = 'Everything loaded, images too'">
<p id="status">Loading…</p>
<script>
document.addEventListener('DOMContentLoaded', () => {
console.log('HTML ready, images may still be loading');
});
</script>
</body>The DOMContentLoaded message appears in the console earlier, because that event does not wait for images, styles and frames. Wait for load only when you need all the resources, for example image dimensions.
Browser support
#Widely available
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Give images
widthandheight. The browser then reserves space, the page does not jump after the image loads, and you do not need to fix the layout inonload. - Put code that needs only the page’s elements in a script with the
deferattribute, not in<body onload>. It will run sooner, without waiting for images.
Related entries
#- <img>An image embedded in the page.
- <body>The visible part of the document: everything the user sees on the page and can interact with.
- <script>Embeds JavaScript code in the page or loads it from a file to give the page behavior.
- <iframe>A frame that embeds another HTML document in the page, for example a YouTube video or a map.
- onclickRuns JavaScript code when an element is clicked. The simplest, but not the best way to handle events.
Practise it in lessons
#Spotted a mistake or missing an example? Write to us.