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'], + ]) + }) })