HTMLImageElement.loading

The HTMLImageElement property loading is a string whose value provides a hint to the user agent that tells the browser how to handle loading images which are currently outside the window's visual viewport. This helps to optimize the loading of the document's contents by postponing loading the image until it's expected to be needed, rather than immediately during the initial page load.

Syntax

let imageLoadScheduling = htmlImageElement.loading;
htmlImageElement.loading = eagerOrLazy;

Value

A DOMString providing a hint to the user agent as to how to best schedule the loading of the image to optimize page performance. The possible values are:

eager
The default behavior, eager tells the browser to load the image as soon as the <img> element is processed.
lazy
Tells the user agent to hold off on loading the image until the browser estimates that it will be needed imminently. For instance, if the user is scrolling through the document, a value of lazy will cause the image to only be loaded shortly before it will appear in the window's visual viewport.

Usage notes

Timing of the load event

The load event is fired when the document has been fully processed. When images are loaded eagerly (which is the default), every image in the document must be fetched before the load event can fire.

By specifying the value lazy for loading, you prevent the image from delaying the load attribute by the amount of time it takes to request, fetch, and process the image.

Images whose loading attribute is set to lazy but are located within the visual viewport immediately upon initial page load are loaded as soon as the layout is known, but their loads do not delay the firing of the load event. In other words, these images aren't loaded immediately when processing the <img> element, but are still loaded as part of the initial page load. They justt don't affect the timing of the load event.

That means that when load fires, it's possible that any lazy-loaded images located in the visual viewport may not yet be visible.

Preventing element shift during image lazy loads

When an image whose loading has been delayed by the loading attribute being set to lazy is finally loaded, the browser will determine the final size of the <img> element based on the style and intrinsic size of the image, then reflow the document as needed to update the positions of elements based on any size change made to the element to fit the image.

To prevent this reflow from occurring, you should explicitly specify the size of the image's presentation using the image element's width and height attributes. By establishing the intrinsic aspect ratio in this manner, you prevent elements from shifting around while the document loads, which can be disconcerting or offputting at best and can cause users to click the wrong thing at worst, depending on the exact timing of the deferred loads and reflows.

Example

The addImageToList() function shown below adds a photo thumbnail to a list of items, using lazy-loading to avoid loading the image from the network until it's actually needed.

function addImageToList(url) {
  const list = document.querySelector("div.photo-list");

  let newItem = document.createElement("div");
  newItem.className = "photo-item";

  let newImg = document.createElement("img");
  newImg.loading = "lazy";
  newImg.width = 320;
  newImg.height = 240;
  newImg.src = url;

  newItem.appendChild(newImg);
  list.appendChild(newItem);
}

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'HTMLImageElement.loading' in that specification.
Living Standard

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
loading
Experimental
Chrome Full support 76Edge Full support 79Firefox Full support 75IE No support NoOpera Full support 63Safari No support No
Notes
No support No
Notes
Notes See bug 196698
WebView Android No support NoChrome Android Full support 76Firefox Android No support NoOpera Android Full support 54Safari iOS No support No
Notes
No support No
Notes
Notes See bug 196698
Samsung Internet Android No support No

Legend

Full support  
Full support
No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
See implementation notes.
See implementation notes.

See also