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 4 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
16 changes: 12 additions & 4 deletions docs/api-reference/next/image.md
View file
Open in desktop
Expand Up @@ -48,15 +48,23 @@ 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` property can represent either the _rendered_ width or _original_ width in pixels, depending on the [`layout`](#layout) and [`sizes`](#sizes) properties.

Required, except for statically imported images, or those with [`layout="fill"`](#layout).
When using `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes`, the `width` property represents the _rendered_ width in pixels, so it will affect how large the image appears.

When using `layout="responsive"`, `layout="fill"`, or `layout="raw"` with `sizes`, the `width` property represents the _original_ width in pixels so it will only affect the aspect ratio.

The `width` property is required, except for [statically imported images](#local-images), or those with `layout="fill"`.

### height

The height of the image, in pixels. Must be an integer without a unit.
The `height` property can represent either the _rendered_ height or _original_ height in pixels, depending on the [`layout`](#layout) and [`sizes`](#sizes) properties.

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

When using `layout="responsive"`, `layout="fill"`, or `layout="raw"` with `sizes`, the `height` property represents the _original_ height in pixels so it will only affect the aspect ratio.

Required, except for statically imported images, or those with [`layout="fill"`](#layout).
The `height` property is required, except for [statically imported images](#local-images), or those with `layout="fill"`.

## 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