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