HTML global attributeGlobal attributes

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 the src attribute, <link> and other elements that load a resource
On this page

Example

#
HTML
<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;
  ">
Preview

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

#
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 as load on the window object.
  • <img>

    The image has been downloaded. With loading="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

#
An image that failed to load
HTML
<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'">
Preview

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.

A page with onload on body and the faster DOMContentLoaded
HTML
<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 width and height. The browser then reserves space, the page does not jump after the image loads, and you do not need to fix the layout in onload.
  • Put code that needs only the page’s elements in a script with the defer attribute, not in <body onload>. It will run sooner, without waiting for images.

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.