Skip to content

Commit

Permalink
Docs: Clarify intrisic vs. rendered size for image height/width prope…
Browse files Browse the repository at this point in the history
  • Loading branch information
delbaoliveira committed Jul 12, 2024
1 parent 0e9479f commit f3fa46e
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down Expand Up @@ -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?**
Expand Down
12 changes: 9 additions & 3 deletions docs/02-app/02-api-reference/01-components/image.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit f3fa46e

Please sign in to comment.