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

Jump to bottom

Update next/image docs for width & height #35188

Merged
merged 7 commits into from Mar 17, 2022
Merged

Update next/image docs for width & height #35188

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c00a86c
Update `next/image` docs for width & height
styfle Mar 16, 2022
97a250a
Link to props
styfle Mar 16, 2022
85d1c87
Apply suggestions from molebox
styfle Mar 17, 2022
6474995
Updates per molebox
styfle Mar 17, 2022
c17f9c5
Merge branch 'canary' into next-image-docs-width-height-improvements
styfle Mar 17, 2022
ef23182
Add missing comma
styfle Mar 17, 2022
f2f3a64
Merge branch 'canary' into next-image-docs-width-height-improvements
styfle Mar 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
20 changes: 16 additions & 4 deletions docs/api-reference/next/image.md
View file
Open in desktop
Expand Up @@ -48,15 +48,27 @@ When using an external URL, you must add it to

### width

The width of the image, in pixels. Must be an integer without a unit.
The width of the image. Must be an integer without a unit.

Required, except for statically imported images, or those with [`layout="fill"`](#layout).
The meaning of the `width` property can change depending on the [`layout`](#layout) and [`sizes`](#sizes) properties since some layouts will stretch to fill the parent container and others will not.

The `width` property represents the _rendered_ width in pixels when `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes` so it will affect how large the image appears.

styfle marked this conversation as resolved.
Show resolved Hide resolved
The `width` property represents the _original_ width in pixels when `layout="responsive"`, `layout="fill"`, or `layout="raw"` with `sizes` so it will only affect the aspect ratio.

styfle marked this conversation as resolved.
Show resolved Hide resolved
Required, except for [statically imported images](#local-images), or those with `layout="fill"`.
styfle marked this conversation as resolved.
Show resolved Hide resolved

### height

The height of the image, in pixels. Must be an integer without a unit.
The height of the image. Must be an integer without a unit.

The meaning of the `height` property can change depending on the [`layout`](#layout) and [`sizes`](#sizes) properties since some layouts will stretch to fill the parent container and others will not.

The `height` property represents the _rendered_ height in pixels when `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes` so it will affect how large the image appears.

styfle marked this conversation as resolved.
Show resolved Hide resolved
The `height` property represents the _original_ height in pixels when `layout="responsive"`, `layout="fill"`, or `layout="raw"` with `sizes` so it will only affect the aspect ratio.
styfle marked this conversation as resolved.
Show resolved Hide resolved

Required, except for statically imported images, or those with [`layout="fill"`](#layout).
Required, except for [statically imported images](#local-images), or those with `layout="fill"`.
styfle marked this conversation as resolved.
Show resolved Hide resolved

## Optional Props

Expand Down
4 changes: 2 additions & 2 deletions docs/basic-features/image-optimization.md
View file
Open in desktop
Expand Up @@ -150,8 +150,8 @@ 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 `height` **and** `width` property
3. Implicitly, by using `layout="fill"` which causes the image to expand to fill its parent element.
2. Explicitly, by including a [`width`](/docs/api-reference/next/image.md#width) and [`height`](/docs/api-reference/next/image.md#height) property
3. Implicitly, by using [`layout="fill"`](/docs/api-reference/next/image.md#layout) which causes the image to expand to fill its parent element.

> ### What if I don't know the size of my images?
>
Expand Down