Unverified Commit 3a459ca9 authored by Steven's avatar Steven Committed by GitHub

chore(next/image)!: mark `onLoadingComplete` as deprecated in favor of `onLoad` (#56944)

## History

We used to pass `onLoad` through directly to the underlying img so `onLoadingComplete` was introduced in order to handle the case when `placeholder="blur"` was used and `onLoad` would trigger before the placeholder was removed.

We have since changed the behavior of `onLoad` so that it acts the same as `onLoadingComplete` and therefore `onLoadingComplete` is no longer needed.

## What is this PR doing?

This PR marks `onLoadingComplete` as deprecated in favor of `onLoad`. In the future, we may remove `onLoadingComplete`.
parent 6ed4fddf
...@@ -40,12 +40,12 @@ export default function Page() { ...@@ -40,12 +40,12 @@ export default function Page() {
Here's a summary of the props available for the Image Component: Here's a summary of the props available for the Image Component:
<div style={{ overflowX: 'auto', width: '100%' }}> <div style={{ overflowX: 'auto', width: '100%' }}>
| Prop | Example | Type | Required | | Prop | Example | Type | Status |
| ----------------------------------------- | ------------------------------------ | --------------- | -------- | | ----------------------------------------- | ------------------------------------ | --------------- | ---------- |
| [`src`](#src) | `src="/profile.png"` | String | Yes | | [`src`](#src) | `src="/profile.png"` | String | Required |
| [`width`](#width) | `width={500}` | Integer (px) | Yes | | [`width`](#width) | `width={500}` | Integer (px) | Required |
| [`height`](#height) | `height={500}` | Integer (px) | Yes | | [`height`](#height) | `height={500}` | Integer (px) | Required |
| [`alt`](#alt) | `alt="Picture of the author"` | String | Yes | | [`alt`](#alt) | `alt="Picture of the author"` | String | Required |
| [`loader`](#loader) | `loader={imageLoader}` | Function | - | | [`loader`](#loader) | `loader={imageLoader}` | Function | - |
| [`fill`](#fill) | `fill={true}` | Boolean | - | | [`fill`](#fill) | `fill={true}` | Boolean | - |
| [`sizes`](#sizes) | `sizes="(max-width: 768px) 100vw"` | String | - | | [`sizes`](#sizes) | `sizes="(max-width: 768px) 100vw"` | String | - |
...@@ -53,7 +53,7 @@ Here's a summary of the props available for the Image Component: ...@@ -53,7 +53,7 @@ Here's a summary of the props available for the Image Component:
| [`priority`](#priority) | `priority={true}` | Boolean | - | | [`priority`](#priority) | `priority={true}` | Boolean | - |
| [`placeholder`](#placeholder) | `placeholder="blur"` | String | - | | [`placeholder`](#placeholder) | `placeholder="blur"` | String | - |
| [`style`](#style) | `style={{objectFit: "contain"}}` | Object | - | | [`style`](#style) | `style={{objectFit: "contain"}}` | Object | - |
| [`onLoadingComplete`](#onloadingcomplete) | `onLoadingComplete={img => done())}` | Function | - | | [`onLoadingComplete`](#onloadingcomplete) | `onLoadingComplete={img => done())}` | Function | Deprecated |
| [`onLoad`](#onload) | `onLoad={event => done())}` | Function | - | | [`onLoad`](#onload) | `onLoad={event => done())}` | Function | - |
| [`onError`](#onerror) | `onError(event => fail()}` | Function | - | | [`onError`](#onerror) | `onError(event => fail()}` | Function | - |
| [`loading`](#loading) | `loading="lazy"` | String | - | | [`loading`](#loading) | `loading="lazy"` | String | - |
...@@ -286,6 +286,8 @@ Remember that the required width and height props can interact with your styling ...@@ -286,6 +286,8 @@ Remember that the required width and height props can interact with your styling
<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} /> <Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />
``` ```
> **Warning**: Deprecated since Next.js 14 in favor of [`onLoad`](#onload).
A callback function that is invoked once the image is completely loaded and the [placeholder](#placeholder) has been removed. A callback function that is invoked once the image is completely loaded and the [placeholder](#placeholder) has been removed.
The callback function will be called with one argument, a reference to the underlying `<img>` element. The callback function will be called with one argument, a reference to the underlying `<img>` element.
...@@ -302,9 +304,9 @@ The callback function will be called with one argument, a reference to the under ...@@ -302,9 +304,9 @@ The callback function will be called with one argument, a reference to the under
<Image onLoad={(e) => console.log(e.target.naturalWidth)} /> <Image onLoad={(e) => console.log(e.target.naturalWidth)} />
``` ```
A callback function that is invoked when the image is loaded. A callback function that is invoked once the image is completely loaded and the [placeholder](#placeholder) has been removed.
The load event might occur before the image placeholder is removed and the image is fully decoded. If you want to wait until the image has fully loaded, use [`onLoadingComplete`](#onloadingcomplete) instead. The callback function will be called with one argument, the Event which has a `target` that references the underlying `<img>` element.
<AppOnly> <AppOnly>
...@@ -445,7 +447,7 @@ The `**` syntax does not work in the middle of the pattern. ...@@ -445,7 +447,7 @@ The `**` syntax does not work in the middle of the pattern.
### `domains` ### `domains`
> **Warning**: We recommend configuring strict [`remotePatterns`](#remotepatterns) instead of `domains` in order to protect your application from malicious users. Only use `domains` if you own all the content served from the domain. > **Warning**: Deprecated since Next.js 14. We recommend configuring strict [`remotePatterns`](#remotepatterns) instead of `domains` in order to protect your application from malicious users. Only use `domains` if you own all the content served from the domain.
Similar to [`remotePatterns`](#remotepatterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images. Similar to [`remotePatterns`](#remotepatterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images.
......
...@@ -81,7 +81,7 @@ export default function SharedModal({ ...@@ -81,7 +81,7 @@ export default function SharedModal({
height={navigation ? 853 : 1280} height={navigation ? 853 : 1280}
priority priority
alt="Next.js Conf image" alt="Next.js Conf image"
onLoadingComplete={() => setLoaded(true)} onLoad={() => setLoaded(true)}
/> />
</motion.div> </motion.div>
</AnimatePresence> </AnimatePresence>
......
...@@ -22,7 +22,7 @@ export default function ProductCard({ product }) { ...@@ -22,7 +22,7 @@ export default function ProductCard({ product }) {
? 'scale-110 blur-2xl grayscale' ? 'scale-110 blur-2xl grayscale'
: 'scale-100 blur-0 grayscale-0' : 'scale-100 blur-0 grayscale-0'
)} )}
onLoadingComplete={() => setLoading(false)} onLoad={() => setLoading(false)}
/> />
</div> </div>
<div className="mt-4 flex items-center justify-between text-base font-medium text-gray-900"> <div className="mt-4 flex items-center justify-between text-base font-medium text-gray-900">
......
...@@ -38,6 +38,10 @@ export type ImageProps = Omit< ...@@ -38,6 +38,10 @@ export type ImageProps = Omit<
placeholder?: PlaceholderValue placeholder?: PlaceholderValue
blurDataURL?: string blurDataURL?: string
unoptimized?: boolean unoptimized?: boolean
/**
* @deprecated Use `onLoad` instead.
* @see https://nextjs.org/docs/app/api-reference/components/image#onload
*/
onLoadingComplete?: OnLoadingComplete onLoadingComplete?: OnLoadingComplete
/** /**
* @deprecated Use `fill` prop instead of `layout="fill"` or change import to `next/legacy/image`. * @deprecated Use `fill` prop instead of `layout="fill"` or change import to `next/legacy/image`.
...@@ -500,7 +504,7 @@ export function getImgProps( ...@@ -500,7 +504,7 @@ export function getImgProps(
} }
if ('ref' in rest) { if ('ref' in rest) {
warnOnce( warnOnce(
`Image with src "${src}" is using unsupported "ref" property. Consider using the "onLoadingComplete" property instead.` `Image with src "${src}" is using unsupported "ref" property. Consider using the "onLoad" property instead.`
) )
} }
...@@ -523,6 +527,12 @@ export function getImgProps( ...@@ -523,6 +527,12 @@ export function getImgProps(
} }
} }
if (onLoadingComplete) {
warnOnce(
`Image with src "${src}" is using deprecated "onLoadingComplete" property. Please use the "onLoad" property instead.`
)
}
for (const [legacyKey, legacyValue] of Object.entries({ for (const [legacyKey, legacyValue] of Object.entries({
layout, layout,
objectFit, objectFit,
......
...@@ -357,6 +357,15 @@ function runTests(mode) { ...@@ -357,6 +357,15 @@ function runTests(mode) {
() => browser.eval(`document.getElementById("msg9").textContent`), () => browser.eval(`document.getElementById("msg9").textContent`),
'loaded 1 img9 with dimensions 400x400' 'loaded 1 img9 with dimensions 400x400'
) )
if (mode === 'dev') {
const warnings = (await browser.log('browser'))
.map((log) => log.message)
.join('\n')
expect(warnings).toMatch(
/Image with src "(.*)" is using deprecated "onLoadingComplete" property/gm
)
}
}) })
it('should callback native onLoad with sythetic event', async () => { it('should callback native onLoad with sythetic event', async () => {
......
...@@ -358,6 +358,15 @@ function runTests(mode) { ...@@ -358,6 +358,15 @@ function runTests(mode) {
() => browser.eval(`document.getElementById("msg9").textContent`), () => browser.eval(`document.getElementById("msg9").textContent`),
'loaded 1 img9 with dimensions 400x400' 'loaded 1 img9 with dimensions 400x400'
) )
if (mode === 'dev') {
const warnings = (await browser.log('browser'))
.map((log) => log.message)
.join('\n')
expect(warnings).toMatch(
/Image with src "(.*)" is using deprecated "onLoadingComplete" property/gm
)
}
}) })
it('should callback native onLoad with sythetic event', async () => { it('should callback native onLoad with sythetic event', async () => {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment