From f3fa46ed1db53d8254d210a070a80ab5a36161fe Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Sat, 13 Jul 2024 00:16:05 +0100
Subject: [PATCH] Docs: Clarify intrisic vs. rendered size for image
 height/width properties (#67496)

re: https://x.com/ericbureltech/status/1809129675270046023
---
 .../06-optimizing/01-images.mdx                      |  4 ++--
 docs/02-app/02-api-reference/01-components/image.mdx | 12 +++++++++---
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/docs/02-app/01-building-your-application/06-optimizing/01-images.mdx b/docs/02-app/01-building-your-application/06-optimizing/01-images.mdx
index 76f210fbb17b2..a665d6fb68f89 100644
--- a/docs/02-app/01-building-your-application/06-optimizing/01-images.mdx
+++ b/docs/02-app/01-building-your-application/06-optimizing/01-images.mdx
@@ -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.
 
-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>
 
@@ -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:
 
 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.
 
 > **What if I don't know the size of my images?**
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 f225c00b0ea39..053fe8ed7d8d6 100644
--- a/docs/02-app/02-api-reference/01-components/image.mdx
+++ b/docs/02-app/02-api-reference/01-components/image.mdx
@@ -63,7 +63,7 @@ Here's a summary of the props available for the Image Component:
 
 ## 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"
 import Image from 'next/image'
@@ -93,16 +93,22 @@ When using an external URL, you must add it to [remotePatterns](#remotepatterns)
 
 ### `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).
 
 ### `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).
 
+> **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`
 
 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.