diff --git a/docs/02-app/02-api-reference/01-components/image.mdx b/docs/02-app/02-api-reference/01-components/image.mdx
index d6143397ced73..440f95b627c05 100644
--- a/docs/02-app/02-api-reference/01-components/image.mdx
+++ b/docs/02-app/02-api-reference/01-components/image.mdx
@@ -461,13 +461,24 @@ For example, when upgrading an existing website from `` to ``, 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 `` 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. |
diff --git a/packages/next/src/shared/lib/get-img-props.ts b/packages/next/src/shared/lib/get-img-props.ts
index f0fcad0cde358..79eaf94062fbb 100644
--- a/packages/next/src/shared/lib/get-img-props.ts
+++ b/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,
diff --git a/test/unit/next-image-get-img-props.test.ts b/test/unit/next-image-get-img-props.test.ts
index e38150f788f57..463467978015a 100644
--- a/test/unit/next-image-get-img-props.test.ts
+++ b/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'],
+ ])
+ })
})