feat(next/image): add support for decoding prop (#70678)

- Backport #70298 to `14.2.x`

Author: styfle

docs/02-app/02-api-reference/01-components/image.mdx

@@ -461,13 +461,24 @@ For example, when upgrading an existing website from `<img>` to `<Image>`, you m
 />
 ```
 
+### decoding
+
+A hint to the browser indicating if it should wait for the image to be decoded before presenting other content updates or not. Defaults to `async`.
+
+Possible values are the following:
+
+- `async` - Asynchronously decode the image and allow other content to be rendered before it completes.
+- `sync` - Synchronously decode the image for atomic presentation with other content.
+- `auto` - No preference for the decoding mode; the browser decides what's best.
+
+Learn more about the [`decoding` attribute](https://developer.mozilla.org/docs/Web/HTML/Element/img#loading).
+
 ### Other Props
 
 Other properties on the `<Image />` component will be passed to the underlying
 `img` element with the exception of the following:
 
 - `srcSet`. Use [Device Sizes](#devicesizes) instead.
-- `decoding`. It is always `"async"`.
 
 ## Configuration Options
 
@@ -1020,6 +1031,7 @@ This `next/image` component uses browser native [lazy loading](https://caniuse.c
 
 | Version    | Changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v14.2.15` | `decoding` prop added.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `v14.2.0`  | `overrideSrc` prop added.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `v14.1.0`  | `getImageProps()` is stable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `v14.0.0`  | `onLoadingComplete` prop and `domains` config deprecated.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

packages/next/src/shared/lib/get-img-props.ts

@@ -252,6 +252,7 @@ export function getImgProps(
     placeholder = 'empty',
     blurDataURL,
     fetchPriority,
+    decoding = 'async',
     layout,
     objectFit,
     objectPosition,
@@ -673,7 +674,7 @@ export function getImgProps(
     fetchPriority,
     width: widthInt,
     height: heightInt,
-    decoding: 'async',
+    decoding,
     className,
     style: { ...imgStyle, ...placeholderStyle },
     sizes: imgAttributes.sizes,

test/unit/next-image-get-img-props.test.ts

@@ -277,4 +277,27 @@ describe('getImageProps()', () => {
       ['src', '/override.png'],
     ])
   })
+  it('should handle decoding=sync', async () => {
+    const { props } = getImageProps({
+      alt: 'a nice desc',
+      src: '/test.png',
+      decoding: 'sync',
+      width: 100,
+      height: 200,
+    })
+    expect(warningMessages).toStrictEqual([])
+    expect(Object.entries(props)).toStrictEqual([
+      ['alt', 'a nice desc'],
+      ['loading', 'lazy'],
+      ['width', 100],
+      ['height', 200],
+      ['decoding', 'sync'],
+      ['style', { color: 'transparent' }],
+      [
+        'srcSet',
+        '/_next/image?url=%2Ftest.png&w=128&q=75 1x, /_next/image?url=%2Ftest.png&w=256&q=75 2x',
+      ],
+      ['src', '/_next/image?url=%2Ftest.png&w=256&q=75'],
+    ])
+  })
 })