Unverified Commit 2fe5d011 authored by Kara's avatar Kara Committed by GitHub

Add "priority" section to Image Optimization doc (#30218)

This change addresses some feedback that some users don't realize
that the `priority` attribute exists and is critical for managing
LCP when using the next/image component. It adds a dedicated
section to the Image Optimization doc that explains how and when
to use the attribute.

Fixes #29624

## Documentation / Examples

- [x] Make sure the linting passes by running `yarn lint`
parent f5b7baca
...@@ -113,6 +113,44 @@ The default loader for Next.js applications uses the built-in Image Optimization ...@@ -113,6 +113,44 @@ The default loader for Next.js applications uses the built-in Image Optimization
Loaders can be defined per-image, or at the application level. Loaders can be defined per-image, or at the application level.
### Priority
You should add the `priority` property to the image that will be the [Largest Contentful Paint (LCP) element](https://web.dev/lcp/#what-elements-are-considered) for each page. Doing so allows Next.js to specially prioritize the image for loading (e.g. through preload tags or priority hints), leading to a meaningful boost in LCP.
The LCP element is typically the largest image or text block visible within the viewport of the page. You can verify which element this is by running the following code in the console of your page and looking at the latest result:
```javascript
new PerformanceObserver((entryList) => {
for (const entry of entryList.getEntries()) {
console.log('LCP candidate:', entry.startTime, entry.element)
}
}).observe({ type: 'largest-contentful-paint', buffered: true })
```
Once you've identified the LCP image, you can add the property like this:
```jsx
import Image from 'next/image'
export default function Home() {
return (
<>
<h1>My Homepage</h1>
<Image
src="/me.png"
alt="Picture of the author"
width={500}
height={500}
priority
/>
<p>Welcome to my homepage!</p>
</>
)
}
```
See more about priority in the [`next/image` component documentation](/docs/api-reference/next/image.md#priority).
## Image Sizing ## Image Sizing
One of the ways that images most commonly hurt performance is through _layout shift_, where the image pushes other elements around on the page as it loads in. This performance problem is so annoying to users that it has its own Core Web Vital, called [Cumulative Layout Shift](https://web.dev/cls/). The way to avoid image-based layout shifts is to [always size your images](https://web.dev/optimize-cls/#images-without-dimensions). This allows the browser to reserve precisely enough space for the image before it loads. One of the ways that images most commonly hurt performance is through _layout shift_, where the image pushes other elements around on the page as it loads in. This performance problem is so annoying to users that it has its own Core Web Vital, called [Cumulative Layout Shift](https://web.dev/cls/). The way to avoid image-based layout shifts is to [always size your images](https://web.dev/optimize-cls/#images-without-dimensions). This allows the browser to reserve precisely enough space for the image before it loads.
......
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