Adding information about the decoding attribute

files/en-us/web/api/htmlimageelement/decode/index.md

@@ -10,8 +10,8 @@ browser-compat: api.HTMLImageElement.decode
 
 The **`decode()`**
 method of the {{domxref("HTMLImageElement")}} interface returns a
-{{jsxref("Promise")}} that resolves when the image is decoded and it is safe to append
-the image to the DOM.
+{{jsxref("Promise")}} that resolves once the image is decoded and it is safe to append
+it to the DOM.
 
 This can be used to initiate loading of the image prior
 to attaching it to an element in the DOM (or adding it to the DOM as a new element), so
@@ -31,7 +31,7 @@ None.
 
 ### Return value
 
-A {{jsxref('Promise')}} which is resolved once the image data is ready to be used.
+A {{jsxref('Promise')}} that fulfills with `undefined` once the image data is ready to be used.
 
 ### Exceptions
 
@@ -51,11 +51,10 @@ low-resolution image with the full-resolution one that's now available.
 
 ## Examples
 
+### Basic usage
+
 The following example shows how to use the `decode()` method to control when
-an image is appended to the DOM. Without a {{jsxref('Promise')}}-returning method, you
-would add the image to the DOM in a {{domxref("Window/load_event", "load")}} event handler, such as by using
-the {{domxref("HTMLImageElement.load_event", "img.onload")}} event handler, and by
-handling the error in the {{domxref("HTMLElement/error_event", "error")}} event's handler.
+an image is appended to the DOM.
 
 ```js
 const img = new Image();
@@ -70,10 +69,45 @@ img
   });
 ```
 
+> **Note:** Without a {{jsxref('Promise')}}-returning method, you
+> would add the image to the DOM in a {{domxref("Window/load_event", "load")}} event handler,
+> and handle the error in the {{domxref("Element/error_event", "error")}} event's handler.
+
+### Avoiding empty images
+
+In the below example, you'll likely get an empty image shown on the page as the image is downloaded:
+
+```js
+const img = new Image();
+img.src = "img/logo.png";
+document.body.appendChild(img);
+```
+
+Using `decode()` will delay inserting the image into the DOM until it is fully downloaded and decoded, thereby avoiding the empty image problem:
+
+```js
+async function getImage() {
+  const img = new Image();
+  img.src = "img/logo.png";
+  await img.decode();
+  document.body.appendChild(img);
+  const p = document.createElement("p");
+  p.textContent = "Image is fully loaded!";
+  document.body.appendChild(p);
+}
+```
+
+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.
+
 ## Specifications
 
 {{Specifications}}
 
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [What does the image decoding attribute actually do?](https://www.tunetheweb.com/blog/what-does-the-image-decoding-attribute-actually-do/) on tunetheweb.com (2023)
+- The {{domxref("HTMLImageElement.decoding")}} property

files/en-us/web/api/htmlimageelement/decoding/index.md

@@ -8,36 +8,71 @@ browser-compat: api.HTMLImageElement.decoding
 
 {{APIRef}}
 
-The **`decoding`** property of the
-{{domxref("HTMLImageElement")}} interface represents a hint given to the browser on how
-it should decode the image.
+The **`decoding`** property of the {{domxref("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`
+- `"sync"`
   - : Decode the image synchronously for atomic presentation with other content.
-- `async`
-  - : Decode the image asynchronously to reduce delay in presenting other content.
-- `auto`
-  - : Default mode, which indicates no preference for the decoding mode.
-    The browser decides what is best for the user.
+- `"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.
 
 ## Usage notes
 
-The `decoding` property allows you to control whether or not the browser is
-allowed to try to parallelize loading your image. If doing so would cause problems, you
-can specify `sync` to disable asynchronous loading. This can be useful when
-applied to {{HTMLElement("img")}} elements, but may be even more so when used for
-offscreen image objects.
+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](/en-US/docs/Glossary/Jank). Using the {{domxref("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.
+
 ```js
 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:
+
+```js
+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 {{domxref("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:
+
+```js
+const img = new Image();
+img.decoding = "async";
+img.src = "img/logo.png";
+document.body.appendChild(img);
 ```
 
 ## Specifications
@@ -47,3 +82,9 @@ img.src = "img/logo.png";
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- The {{domxref("HTMLImageElement.decode()")}} method
+- The {{htmlelement("img")}} element `decoding` attribute
+- [What does the image decoding attribute actually do?](https://www.tunetheweb.com/blog/what-does-the-image-decoding-attribute-actually-do/) on tunetheweb.com (2023)

files/en-us/web/api/svgimageelement/decode/index.md

@@ -10,8 +10,8 @@ browser-compat: api.SVGImageElement.decode
 
 The **`decode()`** method of the
 {{domxref("SVGImageElement")}} interface initiates asynchronous decoding of an image,
-returning a {{jsxref('Promise')}} that resolves once the image data is ready
-for use.
+returning a {{jsxref('Promise')}} that resolves once the image is decoded and it is safe to append
+it to the DOM.
 
 ## Syntax
 
@@ -25,13 +25,44 @@ None.
 
 ### Return value
 
-A {{jsxref('Promise')}} which resolves once the image data is ready to be used, such as
-by appending it to the DOM, replacing an existing image, and so forth.
+A {{jsxref('Promise')}} that fulfills with `undefined` once the image data is ready to be used, for example by appending it to the DOM, replacing an existing image, and so forth.
 
 ### Exceptions
 
 None.
 
+## Examples
+
+In the below example, you'll likely get an empty image shown on the page as the image is downloaded:
+
+```js
+const SVG_NS = "http://www.w3.org/2000/svg";
+const svg = document.querySelector("svg");
+
+const img = document.createElementNS(SVG_NS, "image");
+img.src = "img/logo.svg";
+svg.appendChild(img);
+```
+
+Using `decode()` will delay inserting the image into the DOM until it is fully downloaded and decoded, thereby avoiding the empty image problem:
+
+```js
+const SVG_NS = "http://www.w3.org/2000/svg";
+const svg = document.querySelector("svg");
+
+async function getImage() {
+  const img = document.createElementNS(SVG_NS, "image");
+  img.src = "img/logo.svg";
+  await img.decode();
+  svg.appendChild(img);
+  const text = document.createElementNS(SVG_NS, "text");
+  text.textContent = "Image is fully loaded!";
+  svg.appendChild(text);
+}
+```
+
+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.
+
 ## Specifications
 
 {{Specifications}}
@@ -42,5 +73,5 @@ None.
 
 ## See also
 
-- {{domxref("HTMLImageElement.decode()")}}: The same thing, but for HTML
-  {{HTMLElement("image")}} elements
+- {{domxref("HTMLImageElement.decode()")}}: The same thing, but for HTML `<img>` elements
+- [What does the image decoding attribute actually do?](https://www.tunetheweb.com/blog/what-does-the-image-decoding-attribute-actually-do/) on tunetheweb.com (2023)

files/en-us/web/api/svgimageelement/decoding/index.md

@@ -8,27 +8,80 @@ browser-compat: api.SVGImageElement.decoding
 
 {{APIRef}}
 
-The **`decoding`** property of the {{domxref("SVGImageElement")}} interface represents a hint given to the browser on how it should decode the image.
+The **`decoding`** property of the {{domxref("SVGImageElement")}} interface provides a hint to the browser as to whether it should perform image decoding synchronously or asynchronously.
 
 ## Value
 
 A string representing the decoding hint. Possible values are:
 
-- `sync`
+- `"sync"`
   - : Decode the image synchronously for atomic presentation with other content.
-- `async`
-  - : Decode the image asynchronously to reduce delay in presenting other content.
-- `auto`
-  - : Default mode, which indicates no preference for the decoding mode. The browser decides what is best for the user.
+- `"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.
+
+## 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](/en-US/docs/Glossary/Jank). Using the {{domxref("SVGImageElement.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.
+
 ```js
 const SVG_NS = "http://www.w3.org/2000/svg";
+const svg = document.querySelector("svg");
 
 const img = document.createElementNS(SVG_NS, "image");
 img.decoding = "sync";
 img.setAttribute("href", "img/logo.svg");
+svg.appendChild(img);
+```
+
+Inserting an image after download can make the `decoding` property more relevant:
+
+```js
+async function loadImage(url, elem) {
+  return new Promise((resolve, reject) => {
+    elem.onload = () => resolve(elem);
+    elem.onerror = reject;
+    elem.src = url;
+  });
+}
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+const svg = document.querySelector("svg");
+
+const img = document.createElementNS(SVG_NS, "image");
+await loadImage("img/logo.svg", img);
+// Using `sync` can ensure other content is only updated with the image
+img.decoding = "sync";
+svg.appendChild(img);
+const text = document.createElementNS(SVG_NS, "text");
+text.textContent = "Image is fully loaded!";
+svg.appendChild(text);
+```
+
+A better solution, however, is to use the {{domxref("SVGImageElement.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:
+
+```js
+const SVG_NS = "http://www.w3.org/2000/svg";
+const svg = document.querySelector("svg");
+
+const img = document.createElementNS(SVG_NS, "image");
+img.decoding = "async";
+img.setAttribute("href", "img/logo.svg");
+svg.appendChild(img);
 ```
 
 ## Specifications
@@ -41,4 +94,5 @@ img.setAttribute("href", "img/logo.svg");
 
 ## See also
 
-- [`<img>`: The Image Embed element](/en-US/docs/Web/HTML/Element/img)
+- The {{domxref("SVGImageElement.decode()")}} method
+- The SVG {{SVGElement("image")}} element {{SVGAttr("decoding")}} attribute.

files/en-us/web/api/svgimageelement/index.md

@@ -18,7 +18,7 @@ _This interface also inherits properties from its parent, {{domxref("SVGGraphics
 - {{domxref("SVGImageElement.href")}} {{ReadOnlyInline}}
   - : An {{domxref("SVGAnimatedString")}} corresponding to the {{SVGAttr("href")}} or {{SVGAttr("xlink:href")}} {{deprecated_inline}} attribute of the given {{SVGElement("image")}} element.
 - {{domxref("SVGImageElement.decoding")}}
-  - : A string representing a hint given to the browser on how it should decode the image.
+  - : Represents a hint given to the browser on how it should decode the image. If this value is provided, it must be one of the possible permitted values: `"sync"` to decode the image synchronously, `"async"` to decode it asynchronously, or `"auto"` to indicate no preference (which is the default).
 - {{domxref("SVGImageElement.height")}} {{ReadOnlyInline}}
   - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("height")}} attribute of the given {{SVGElement("image")}} element.
 - {{domxref("SVGImageElement.preserveAspectRatio")}} {{ReadOnlyInline}}

files/en-us/web/html/element/img/index.md

@@ -92,14 +92,20 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
 
 - `decoding`
 
-  - : Provides an image decoding hint to the browser. Allowed values:
+  - : This attribute provides a hint to the browser as to whether it should perform image decoding along with rendering the other DOM content in a single presentation step that looks more "correct" (`sync`), or render and present the other DOM content first and then decode the image and present it later (`async`). In practice, `async` means that the next paint does not wait for the image to decode.
+
+    It is often difficult to perceive any noticeable effect when using `decoding` on static `<img>` elements. They'll likely be initially rendered as empty images while the image files are fetched (either from the network or from the cache) and then handled independently anyway, so the "syncing" of content updates is less apparent. However, the blocking of rendering while decoding happens, while often quite small, _can_ be measured — even if it is difficult to observe with the human eye. See [What does the image decoding attribute actually do?](https://www.tunetheweb.com/blog/what-does-the-image-decoding-attribute-actually-do/) for a more detailed analysis (tunetheweb.com, 2023).
+
+    Using different `decoding` types can result in more noticeable differences when dynamically inserting `<img>` elements into the DOM via JavaScript — see {{domxref("HTMLImageElement.decoding")}} for more details.
+
+    Allowed values:
 
     - `sync`
-      - : Decode the image synchronously, for atomic presentation with other content.
+      - : Decode the image synchronously along with rendering the other DOM content, and present everything together.
     - `async`
-      - : Decode the image asynchronously, to reduce delay in presenting other content.
+      - : Decode the image asynchronously, after rendering and presenting the other DOM content.
     - `auto`
-      - : Default: no preference for the decoding mode. The browser decides what is best for the user.
+      - : No preference for the decoding mode; the browser decides what is best for the user. This is the default value.
 
 - `elementtiming`