Adding information about the decoding attribute

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

@@ -51,6 +51,8 @@ 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
@@ -70,6 +72,32 @@ img
   });
 ```
 
+### 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}}

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

@@ -8,36 +8,68 @@ 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 default values — Chromium defaults to `"sync"`, Firefox defaults to `"async"`, and Safari seems to use different values in different 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.
+In theory, this 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 `decoding` attribute for APIs is often not that useful, and there are often better ways of handling this.
+
+For images that are not downloaded before being inserted into the DOM, the browser will likely render the empty image initially, and then handle the image when it is available, independently of the other content anyway.
+
+For images that are downloaded before being inserted into the DOM, using the {{domxref("HTMLImageElement.decode()")}} method is a better way to assure atomic presentation without holding up other content.
 
 ## 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 +79,8 @@ img.src = "img/logo.png";
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- The {{domxref("HTMLImageElement.decode()")}} method
+- The {{htmlelement("img")}} element `decoding` attribute.

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 image is decoded and it is safe to append
+the image to the DOM.
 
 ## Syntax
 
@@ -32,6 +32,38 @@ by appending it to the DOM, replacing an existing image, and so forth.
 
 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}}

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

@@ -8,27 +8,77 @@ 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 default values — Chromium defaults to `"sync"`, Firefox defaults to `"async"`, and Safari seems to use different values in different circumstances.
+
+## Usage notes
+
+In theory, this 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 `decoding` attribute for APIs is often not that useful, and there are often better ways of handling this.
+
+For images that are not downloaded before being inserted into the DOM, the browser will likely render the empty image initially, and then handle the image when it is available, independently of the other content anyway.
+
+For images that are downloaded before being inserted into the DOM, using the {{domxref("HTMLImageElement.decode()")}} method is a better way to assure atomic presentation without holding up other content.
 
 ## 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 +91,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")}} 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.
+
+    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`
 
@@ -156,7 +162,7 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
 
   - : One or more strings separated by commas, indicating a set of source sizes. Each source size consists of:
 
-    1. A [media condition](/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#syntax). This must be omitted for the last item in the list.
+    1. A [media condition](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries). This must be omitted for the last item in the list.
     2. A source size value.
 
     Media Conditions describe properties of the _viewport_, not of the _image_. For example, `(max-height: 500px) 1000px` proposes to use a source of 1000px width, if the _viewport_ is not higher than 500px.

files/en-us/web/svg/attribute/decoding/index.md

@@ -0,0 +1,47 @@
+---
+title: decoding
+slug: Web/SVG/Attribute/decoding
+page-type: svg-attribute
+browser-compat: svg.elements.image.decoding
+---
+
+{{SVGRef}}
+
+The `decoding` attribute, valid on {{SVGElement("image")}} elements, provides a hint to the browser as to whether it should perform image decoding along with rendering other content in a single presentation step that looks more "correct" (`sync`), or render and present the other 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 `<image>` 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.
+
+Using different `decoding` types can result in more noticeable differences when dynamically inserting `<image>` elements into the DOM via JavaScript — see {{domxref("SVGImageElement.decoding")}} for more details.
+
+Allowed values:
+
+- `sync`
+  - : Decode the image synchronously along with rendering the other content, and present everything together.
+- `async`
+  - : Decode the image asynchronously, after rendering and presenting the other content.
+- `auto`
+  - : No preference for the decoding mode; the browser decides what is best for the user. This is the default value.
+
+## Example
+
+```html
+<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
+  <image
+    href="https://example.com/mdn_logo_dark.png"
+    height="200"
+    width="200"
+    decoding="async" />
+</svg>
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [SVGImageElement: decoding property](/en-US/docs/Web/API/SVGImageElement/decoding)

files/en-us/web/svg/element/image/index.md

@@ -41,6 +41,7 @@ SVG files displayed with `<image>` are [treated as an image](/en-US/docs/Web/SVG
 - {{SVGAttr("href")}} and {{SVGAttr("xlink:href")}}: Points at a URL for the image file.
 - {{SVGAttr("preserveAspectRatio")}}: Controls how the image is scaled.
 - {{SVGAttr("crossorigin")}}: Defines the value of the credentials flag for CORS requests.
+- {{SVGAttr("decoding")}}: Provides a hint to the browser as to whether it should perform image decoding synchronously or asynchronously.
 
 ## DOM Interface