Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Jul 12, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
73d97e5
Clarify intrisic vs. rendered size for height/width properties
delbaoliveira Jul 5, 2024
ec9a82b
Tweak
delbaoliveira Jul 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/02-app/01-building-your-application/06-optimizing/01-images.mdx
View file
Open in desktop
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
View file
Open in desktop
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
Loading