HTMLImageElement: decoding property
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
The decoding
property of the HTMLImageElement
interface provides a hint to the browser as to how it should decode the image. More specifically, whether it should wait for the image to be decoded before presenting other content updates or not.
Value
A string representing the decoding hint. Possible values are:
"sync"
-
Decode the image synchronously for atomic presentation with other content.
"async"
-
Decode the image asynchronously and allow other content to be rendered before this completes.
"auto"
-
No preference for the decoding mode; the browser decides what is best for the user. This is the default value, but different browsers have different defaults:
- Chromium defaults to
"sync"
. - Firefox defaults to
"async"
. - Safari defaults to
"sync"
except in a small number of circumstances.
- Chromium defaults to
Usage notes
The decoding
property provides a hint to the browser as to whether it should perform image decoding along with other tasks in a single step ("sync"
), or allow other content to be rendered before this completes ("async"
). In reality, the differences between the two values are often difficult to perceive and, where there are differences, there is often a better way.
For images that are inserted into the DOM inside the viewport, "async"
can result in flashes of unstyled content, while "sync"
can result in small amounts of jank. Using the HTMLImageElement.decode()
method is usually a better way to achieve atomic presentation without holding up other content.
For images inserted into the DOM outside of the viewport, modern browsers will usually decode them before they are scrolled into view and there will be no noticeable difference using either value.
Examples
In the below example, you'll likely get an empty image shown on the page as the image is downloaded. Setting decoding
won't prevent that.
const img = new Image();
img.decoding = "sync";
img.src = "img/logo.png";
document.body.appendChild(img);
Inserting an image after download can make the decoding
property more relevant:
async function loadImage(url, elem) {
return new Promise((resolve, reject) => {
elem.onload = () => resolve(elem);
elem.onerror = reject;
elem.src = url;
});
}
const img = new Image();
await loadImage("img/logo.png", img);
// Using `sync` can ensure other content is only updated with the image
img.decoding = "sync";
document.body.appendChild(img);
const p = document.createElement("p");
p.textContent = "Image is fully loaded!";
document.body.appendChild(p);
A better solution, however, is to use the HTMLImageElement.decode()
method to solve this problem. It provides a way to asynchronously decode an image, delaying inserting it into the DOM until it is fully downloaded and decoded, thereby avoiding the empty image problem mentioned above. This is particularly useful if you're dynamically swapping an existing image for a new one, and also prevents unrelated paints outside of this code from being held up while the image is decoding.
Using img.decoding = "async"
may avoid holding up other content from displaying if the decoding time is long:
const img = new Image();
img.decoding = "async";
img.src = "img/logo.png";
document.body.appendChild(img);
Specifications
Specification |
---|
HTML Standard # dom-img-decoding |
Browser compatibility
BCD tables only load in the browser
See also
- The
HTMLImageElement.decode()
method - The
<img>
elementdecoding
attribute - What does the image decoding attribute actually do? on tunetheweb.com (2023)