From c00a86c6ddb214d7ab72894023cc9e4d0e9f6904 Mon Sep 17 00:00:00 2001 From: Steven Date: Wed, 16 Mar 2022 10:05:12 -0400 Subject: [PATCH 1/5] Update `next/image` docs for width & height --- docs/api-reference/next/image.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 4035fa8c65ec..46a14e31d0d6 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -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. + +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. + +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 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. + +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. -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"`. ## Optional Props From 97a250aefa2e8a15a62fb7fd8e490e49b7b34d27 Mon Sep 17 00:00:00 2001 From: Steven Date: Wed, 16 Mar 2022 10:09:49 -0400 Subject: [PATCH 2/5] Link to props --- docs/basic-features/image-optimization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/basic-features/image-optimization.md b/docs/basic-features/image-optimization.md index 9de528f1910b..0c55837410ec 100644 --- a/docs/basic-features/image-optimization.md +++ b/docs/basic-features/image-optimization.md @@ -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? > From 85d1c87f681644342c20662e03c43704575e11a6 Mon Sep 17 00:00:00 2001 From: Steven Date: Thu, 17 Mar 2022 12:34:14 -0400 Subject: [PATCH 3/5] Apply suggestions from molebox Co-authored-by: Rich Haines --- docs/api-reference/next/image.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 46a14e31d0d6..09ef00e0a1c2 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -52,11 +52,10 @@ The width of the image. Must be an integer without a unit. 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. - +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. 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. -Required, except for [statically imported images](#local-images), or those with `layout="fill"`. +The width property is required, except for [statically imported images](#local-images), or those with `layout="fill"`. ### height @@ -64,11 +63,10 @@ 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. - +When using `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes`, the `width` property represents the _rendered_ height in pixels, so it will affect how large the image appears. 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. -Required, except for [statically imported images](#local-images), or those with `layout="fill"`. +The `height` property is required, except for [statically imported images](#local-images), or those with `layout="fill"`. ## Optional Props From 6474995a110f5fdd896645c05c18cecd14cb40b2 Mon Sep 17 00:00:00 2001 From: Steven Date: Thu, 17 Mar 2022 12:40:13 -0400 Subject: [PATCH 4/5] Updates per molebox --- docs/api-reference/next/image.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 09ef00e0a1c2..e9c54b323e62 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -48,23 +48,21 @@ When using an external URL, you must add it to ### width -The width of the image. Must be an integer without a unit. - -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 can represent either the _rendered_ width or _original_ width in pixels, depending on the [`layout`](#layout) and [`sizes`](#sizes) properties. 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. -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. -The width property is required, except for [statically imported images](#local-images), or those with `layout="fill"`. +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. 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. -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. +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="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes`, the `width` property represents the _rendered_ height in pixels, so it will affect how large the image appears. -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. +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. The `height` property is required, except for [statically imported images](#local-images), or those with `layout="fill"`. From ef2318200ce9e4d72f4bd458e2f294b976b808ec Mon Sep 17 00:00:00 2001 From: Steven Date: Thu, 17 Mar 2022 13:51:18 -0400 Subject: [PATCH 5/5] Add missing comma --- docs/api-reference/next/image.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index e9c54b323e62..2e75c38e14e7 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -52,7 +52,7 @@ The `width` property can represent either the _rendered_ width or _original_ wid 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. +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"`. @@ -62,7 +62,7 @@ The `height` property can represent either the _rendered_ height or _original_ h 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. +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. The `height` property is required, except for [statically imported images](#local-images), or those with `layout="fill"`.