Unverified Commit f3fa46ed authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs: Clarify intrisic vs. rendered size for image height/width properties (#67496)

re: https://x.com/ericbureltech/status/1809129675270046023
parent 0e9479f5
...@@ -41,7 +41,7 @@ You can then define the `src` for your image (either local or remote). ...@@ -41,7 +41,7 @@ You can then define the `src` for your image (either local or remote).
To use a local image, `import` your `.jpg`, `.png`, or `.webp` image files. To use a local image, `import` your `.jpg`, `.png`, or `.webp` image files.
Next.js will [automatically determine](#image-sizing) the `width` and `height` of your image based on the imported file. These values are used to prevent [Cumulative Layout Shift](https://nextjs.org/learn/seo/web-performance/cls) while your image is loading. Next.js will [automatically determine](#image-sizing) the intrisic `width` and `height` of your image based on the imported file. These values are used to determine the image ratio and prevent [Cumulative Layout Shift](https://nextjs.org/learn/seo/web-performance/cls) while your image is loading.
<AppOnly> <AppOnly>
...@@ -203,7 +203,7 @@ One of the ways that images most commonly hurt performance is through _layout sh ...@@ -203,7 +203,7 @@ One of the ways that images most commonly hurt performance is through _layout sh
Because `next/image` is designed to guarantee good performance results, it cannot be used in a way that will contribute to layout shift, and **must** be sized in one of three ways: Because `next/image` is designed to guarantee good performance results, it cannot be used in a way that will contribute to layout shift, and **must** be sized in one of three ways:
1. Automatically, using a [static import](#local-images) 1. Automatically, using a [static import](#local-images)
2. Explicitly, by including a [`width`](/docs/app/api-reference/components/image#width) and [`height`](/docs/app/api-reference/components/image#height) property 2. Manually, by including a [`width`](/docs/app/api-reference/components/image#width) and [`height`](/docs/app/api-reference/components/image#height) property used to determine the image's aspect ratio.
3. Implicitly, by using [fill](/docs/app/api-reference/components/image#fill) which causes the image to expand to fill its parent element. 3. Implicitly, by using [fill](/docs/app/api-reference/components/image#fill) which causes the image to expand to fill its parent element.
> **What if I don't know the size of my images?** > **What if I don't know the size of my images?**
......
...@@ -63,7 +63,7 @@ Here's a summary of the props available for the Image Component: ...@@ -63,7 +63,7 @@ Here's a summary of the props available for the Image Component:
## Required Props ## Required Props
The Image Component requires the following properties: `src`, `width`, `height`, and `alt`. The Image Component requires the following properties: `src`, `alt`, `width` and `height` (or `fill`).
```jsx filename="app/page.js" ```jsx filename="app/page.js"
import Image from 'next/image' import Image from 'next/image'
...@@ -93,16 +93,22 @@ When using an external URL, you must add it to [remotePatterns](#remotepatterns) ...@@ -93,16 +93,22 @@ When using an external URL, you must add it to [remotePatterns](#remotepatterns)
### `width` ### `width`
The `width` property represents the _rendered_ width in pixels, so it will affect how large the image appears. The `width` property represents the _intrisic_ image width in pixels.
Required, except for [statically imported images](/docs/app/building-your-application/optimizing/images#local-images) or images with the [`fill` property](#fill). Required, except for [statically imported images](/docs/app/building-your-application/optimizing/images#local-images) or images with the [`fill` property](#fill).
### `height` ### `height`
The `height` property represents the _rendered_ height in pixels, so it will affect how large the image appears. The `height` property represents the _intrisic_ image height in pixels.
Required, except for [statically imported images](/docs/app/building-your-application/optimizing/images#local-images) or images with the [`fill` property](#fill). Required, except for [statically imported images](/docs/app/building-your-application/optimizing/images#local-images) or images with the [`fill` property](#fill).
> **Good to know:**
>
> - Combined, both `width` and `height` properties are used to determine the aspect ratio of the image which used by browsers to reserve space for the image before it loads.
> - The intrinsic size does not always mean the rendered size in the browser, which will be determined by the parent container. For example, if the parent container is smaller than the intrinsic size, the image will be scaled down to fit the container.
> - You can use the [`fill`](#fill) property when the width and height are unknown.
### `alt` ### `alt`
The `alt` property is used to describe the image for screen readers and search engines. It is also the fallback text if images have been disabled or an error occurs while loading the image. The `alt` property is used to describe the image for screen readers and search engines. It is also the fallback text if images have been disabled or an error occurs while loading the image.
......
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