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 ca60b53ef18b2..cd1af92a62773 100644
--- a/docs/02-app/02-api-reference/01-components/image.mdx
+++ b/docs/02-app/02-api-reference/01-components/image.mdx
@@ -467,13 +467,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
@@ -1022,7 +1033,7 @@ This `next/image` component uses browser native [lazy loading](https://caniuse.c
| Version | Changes |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `v15.0.0` | `contentDispositionType` configuration default changed to `attachment`. |
+| `v15.0.0` | `decoding` prop added. `contentDispositionType` configuration default changed to `attachment`. |
| `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 8f6ad37c69e98..157dfa16e54c7 100644
--- a/packages/next/src/shared/lib/get-img-props.ts
+++ b/packages/next/src/shared/lib/get-img-props.ts
@@ -254,6 +254,7 @@ export function getImgProps(
placeholder = 'empty',
blurDataURL,
fetchPriority,
+ decoding = 'async',
layout,
objectFit,
objectPosition,
@@ -684,7 +685,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 d650cc85286a7..19a2e4125ba82 100644
--- a/test/unit/next-image-get-img-props.test.ts
+++ b/test/unit/next-image-get-img-props.test.ts
@@ -302,4 +302,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'],
+ ])
+ })
})