From b176c9a53c8c8130a4650b68a3a60fb646227822 Mon Sep 17 00:00:00 2001 From: Alex Castle Date: Wed, 3 Aug 2022 13:28:51 -0700 Subject: [PATCH 1/8] Enhance sizes documentation for next/image --- docs/api-reference/next/image.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 82e4830c8f28d..1e60a5e8c87f3 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -131,15 +131,38 @@ const MyImage = (props) => { ### sizes -A string that provides information about how wide the image will be at different breakpoints. Defaults to `100vw` (the full width of the screen) when using `layout="responsive"` or `layout="fill"`. +A string that provides information about how wide the image will be at different breakpoints. Has important performance ramifications for images using `layout="responsive"` or `layout="fill"`. -If you are using `layout="fill"` or `layout="responsive"` it's important to assign `sizes` for any image that takes up less than the full viewport width. +The `sizes` property serves two important purposes related to image performance: -For example, when the parent element will constrain the image to always be less than half the viewport width, use `sizes="50vw"`. Without `sizes`, the image will be sent at twice the necessary resolution, decreasing performance. +First, the value of `sizes` is used by the browser to determine which of the image urls from the [`srcset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) to download. When the browser chooses, it does not yet know the size of the image on the page, so it assumes that the image will take up the entire width of the screen, and selects an image from the srcset that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. + +Second, the `sizes` value is parsed and used to trim the values in the automatically-created `srcset`. For images using `layout="responsive"` or `layout="fill"`, a large srcset is generated to cover all possible image sizes. If the `sizes` property value includes percentage-based sizes, such as `50vw`, then the srcset is trimmed to not include any values which are too small to ever be necessary, based on that value. + +For example, if you know your styling will cause an image to be full-width on mobile devices, but in a 3-column layout on desktop displays, you should include a sizes property such as the following: + +```js +import Image from 'next/image' + +const MyImage = (props) => { + return ( + + ) +} +``` + +This will reduce the file size of images downloaded in the desktop view by a factor of 9. This can have a dramatic effect on performance metrics. If you are using `layout="intrinsic"` or `layout="fixed"`, then `sizes` is not needed because the upper bound width is constrained already. -[Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes). +Learn more about `srcset` and `sizes`: +[web.dev](https://web.dev/learn/design/responsive-images/#sizes) +[mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) ### quality From 1dfa292c00bfa2abb3dfed374da77e8cc0a78829 Mon Sep 17 00:00:00 2001 From: Alex Castle Date: Wed, 3 Aug 2022 14:32:26 -0700 Subject: [PATCH 2/8] Update docs/api-reference/next/image.md Co-authored-by: Steven --- 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 1e60a5e8c87f3..2ea4d8e9cb268 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -161,8 +161,8 @@ This will reduce the file size of images downloaded in the desktop view by a fac If you are using `layout="intrinsic"` or `layout="fixed"`, then `sizes` is not needed because the upper bound width is constrained already. Learn more about `srcset` and `sizes`: -[web.dev](https://web.dev/learn/design/responsive-images/#sizes) -[mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) +- [web.dev](https://web.dev/learn/design/responsive-images/#sizes) +- [mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) ### quality From 6e51bd2fc67bfdc9ee25e4c098dead5fdc1730bd Mon Sep 17 00:00:00 2001 From: Alex Castle Date: Wed, 3 Aug 2022 14:32:44 -0700 Subject: [PATCH 3/8] Update docs/api-reference/next/image.md Co-authored-by: Steven --- docs/api-reference/next/image.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 2ea4d8e9cb268..ccc498fe3dc4f 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -147,7 +147,7 @@ import Image from 'next/image' const MyImage = (props) => { return ( Date: Wed, 3 Aug 2022 14:37:11 -0700 Subject: [PATCH 4/8] Update docs/api-reference/next/image.md Co-authored-by: Steven --- docs/api-reference/next/image.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index ccc498fe3dc4f..7b730092efdbc 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -131,7 +131,7 @@ const MyImage = (props) => { ### sizes -A string that provides information about how wide the image will be at different breakpoints. Has important performance ramifications for images using `layout="responsive"` or `layout="fill"`. +A string that provides information about how wide the image will be at different breakpoints. The value of `sizes` will greatly affect performance for images using `layout="responsive"` or `layout="fill"`. It will be ignored for images using `layout="intrinsic"` or `layout="fixed"`. The `sizes` property serves two important purposes related to image performance: From 34c0295a58ef915bbf3a806e7af864817ec8e006 Mon Sep 17 00:00:00 2001 From: Alex Castle Date: Wed, 3 Aug 2022 15:15:21 -0700 Subject: [PATCH 5/8] Enhance sizes documentation for future image --- docs/api-reference/next/future/image.md | 30 +++++++++++++++++++++--- docs/api-reference/next/image.md | 31 +++++++++++-------------- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/docs/api-reference/next/future/image.md b/docs/api-reference/next/future/image.md index 437af9d77c3d7..e6ab727a78928 100644 --- a/docs/api-reference/next/future/image.md +++ b/docs/api-reference/next/future/image.md @@ -251,11 +251,35 @@ See also: ### sizes -A string that provides information about how wide the image will be at different breakpoints. +A string that provides information about how wide the image will be at different breakpoints. The value of `sizes` will greatly affect performance for images using [`fill`](#fill) or which are styled to have a responsive size. -It's important to assign `sizes` for responsive images that takes up less than the full viewport width. For example, when the parent element will constrain the image to always be less than half the viewport width, use `sizes="50vw"`. Without `sizes`, the image will be sent at twice the necessary resolution, decreasing performance. +The `sizes` property serves two important purposes related to image performance: -[Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes). +First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/future/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value, a default value of `100vw` (full screen width) is used. + +Second, the `sizes` property configures how `next/future/image` automatically generates an image source set. If no `sizes` value is present, a small source set is generated, suitable for a fixed-size image. If `sizes` is defined, a large source set is generated, suitable for a responsive image. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary. + +For example, if you know your styling will cause an image to be full-width on mobile devices, in a 2-column layout on tablets, and a 3-column layout on desktop displays, you should include a sizes property such as the following: + +```js +import Image from 'next/future/image' +// ... + +; +``` + +This example `sizes` would reduce the file size of images downloaded in the desktop view by a factor of 9. This can have a dramatic effect on performance metrics. + +Learn more about `srcset` and `sizes`: + +- [web.dev](https://web.dev/learn/design/responsive-images/#sizes) +- [mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) ### quality diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 7b730092efdbc..c9d6b6a2f32d2 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -135,32 +135,29 @@ A string that provides information about how wide the image will be at different The `sizes` property serves two important purposes related to image performance: -First, the value of `sizes` is used by the browser to determine which of the image urls from the [`srcset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) to download. When the browser chooses, it does not yet know the size of the image on the page, so it assumes that the image will take up the entire width of the screen, and selects an image from the srcset that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. +First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value, a default value of `100vw` (full screen width) is used. -Second, the `sizes` value is parsed and used to trim the values in the automatically-created `srcset`. For images using `layout="responsive"` or `layout="fill"`, a large srcset is generated to cover all possible image sizes. If the `sizes` property value includes percentage-based sizes, such as `50vw`, then the srcset is trimmed to not include any values which are too small to ever be necessary, based on that value. +Second, the `sizes` value is parsed and used to trim the values in the automatically-created source set. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary. -For example, if you know your styling will cause an image to be full-width on mobile devices, but in a 3-column layout on desktop displays, you should include a sizes property such as the following: +For example, if you know your styling will cause an image to be full-width on mobile devices, in a 2-column layout on tablets, and a 3-column layout on desktop displays, you should include a sizes property such as the following: ```js import Image from 'next/image' - -const MyImage = (props) => { - return ( - - ) -} +// ... + +; ``` -This will reduce the file size of images downloaded in the desktop view by a factor of 9. This can have a dramatic effect on performance metrics. - -If you are using `layout="intrinsic"` or `layout="fixed"`, then `sizes` is not needed because the upper bound width is constrained already. +This example `sizes` would reduce the file size of images downloaded in the desktop view by a factor of 9. This can have a dramatic effect on performance metrics. Learn more about `srcset` and `sizes`: + - [web.dev](https://web.dev/learn/design/responsive-images/#sizes) - [mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) From 48905bce69ccfaaca807f1305153f5bb1edb36a8 Mon Sep 17 00:00:00 2001 From: Alex Castle Date: Tue, 9 Aug 2022 11:18:02 -0700 Subject: [PATCH 6/8] Clarify sizes docs --- docs/api-reference/next/future/image.md | 25 +++++++++++++------------ docs/api-reference/next/image.md | 21 +++++++++++---------- 2 files changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/api-reference/next/future/image.md b/docs/api-reference/next/future/image.md index e6ab727a78928..77ceee46d3331 100644 --- a/docs/api-reference/next/future/image.md +++ b/docs/api-reference/next/future/image.md @@ -255,26 +255,27 @@ A string that provides information about how wide the image will be at different The `sizes` property serves two important purposes related to image performance: -First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/future/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value, a default value of `100vw` (full screen width) is used. +First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/future/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value in an image with the `fill` property, a default value of `100vw` (full screen width) is used. Second, the `sizes` property configures how `next/future/image` automatically generates an image source set. If no `sizes` value is present, a small source set is generated, suitable for a fixed-size image. If `sizes` is defined, a large source set is generated, suitable for a responsive image. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary. For example, if you know your styling will cause an image to be full-width on mobile devices, in a 2-column layout on tablets, and a 3-column layout on desktop displays, you should include a sizes property such as the following: ```js -import Image from 'next/future/image' -// ... - -; +import Image from 'next/image' + +;
+ +
``` -This example `sizes` would reduce the file size of images downloaded in the desktop view by a factor of 9. This can have a dramatic effect on performance metrics. +This example `sizes` could have a dramatic effect on performance metrics. Without the `33vw` sizes, the image selected from the server would be 3 times as wide as it needs to be. Because file size is proportional to the square of the width, without `sizes` the user would download an image that's 9 times larger than necessary. Learn more about `srcset` and `sizes`: diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index c9d6b6a2f32d2..5d5002b3a26e4 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -143,18 +143,19 @@ For example, if you know your styling will cause an image to be full-width on mo ```js import Image from 'next/image' -// ... - -; + +;
+ +
``` -This example `sizes` would reduce the file size of images downloaded in the desktop view by a factor of 9. This can have a dramatic effect on performance metrics. +This example `sizes` could have a dramatic effect on performance metrics. Without the `33vw` sizes, the image selected from the server would be 3 times as wide as it needs to be. Because file size is proportional to the square of the width, without `sizes` the user would download an image that's 9 times larger than necessary. Learn more about `srcset` and `sizes`: From 226eb46072877c692e8c4d9e86b3ea3d826c6c4f Mon Sep 17 00:00:00 2001 From: Steven Date: Tue, 9 Aug 2022 15:03:33 -0400 Subject: [PATCH 7/8] Fix lint --- docs/api-reference/next/future/image.md | 2 +- docs/api-reference/next/image.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-reference/next/future/image.md b/docs/api-reference/next/future/image.md index 77ceee46d3331..9a591741e7d80 100644 --- a/docs/api-reference/next/future/image.md +++ b/docs/api-reference/next/future/image.md @@ -255,7 +255,7 @@ A string that provides information about how wide the image will be at different The `sizes` property serves two important purposes related to image performance: -First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/future/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value in an image with the `fill` property, a default value of `100vw` (full screen width) is used. +First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/future/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is the same size or larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value in an image with the `fill` property, a default value of `100vw` (full screen width) is used. Second, the `sizes` property configures how `next/future/image` automatically generates an image source set. If no `sizes` value is present, a small source set is generated, suitable for a fixed-size image. If `sizes` is defined, a large source set is generated, suitable for a responsive image. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary. diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 5d5002b3a26e4..6415fa9573dbc 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -135,7 +135,7 @@ A string that provides information about how wide the image will be at different The `sizes` property serves two important purposes related to image performance: -First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is just larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value, a default value of `100vw` (full screen width) is used. +First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is the same size or larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value, a default value of `100vw` (full screen width) is used. Second, the `sizes` value is parsed and used to trim the values in the automatically-created source set. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary. From 32c991c26c1e54ccd69cd2b3881a2e5e28686a40 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 9 Aug 2022 14:25:33 -0500 Subject: [PATCH 8/8] lint-fix --- docs/api-reference/next/future/image.md | 1 - docs/api-reference/next/image.md | 1 - 2 files changed, 2 deletions(-) diff --git a/docs/api-reference/next/future/image.md b/docs/api-reference/next/future/image.md index 9a591741e7d80..c81aded6bd121 100644 --- a/docs/api-reference/next/future/image.md +++ b/docs/api-reference/next/future/image.md @@ -263,7 +263,6 @@ For example, if you know your styling will cause an image to be full-width on mo ```js import Image from 'next/image' - ;