From 2b3660b8a5c2811a1ef459c4fadfdc68c797534e Mon Sep 17 00:00:00 2001
From: Alex Castle <atcastle@gmail.com>
Date: Tue, 4 Oct 2022 22:29:28 -0700
Subject: [PATCH] docs(common): update ngOptimizedImage sizes attribute docs

Update the docs to make the sizes documentation more readable
---
 aio/content/guide/image-directive.md | 40 +++++++++++++++-------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/aio/content/guide/image-directive.md b/aio/content/guide/image-directive.md
index d1233ed10d1c29..ddca51c255bc8c 100644
--- a/aio/content/guide/image-directive.md
+++ b/aio/content/guide/image-directive.md
@@ -91,9 +91,9 @@ You can typically fix this by adding `height: auto` or `width: auto` to your ima
 
 Defining a [`srcset` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) ensures that the browser requests an image at the right size for your user's viewport, so it doesn't waste time downloading an image that's too large. 'NgOptimizedImage' generates an appropriate `srcset` for the image, based on the presence and value of the [`sizes` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) on the image tag.
 
-#### Fixed size images
+#### Fixed-size images
 
-If your image should be "fixed" in size  (i.e. the same size across devices), there is no need to set a `sizes` attribute. A `srcset` can be generated automatically from the image's width and height attributes with no further input required. 
+If your image should be "fixed" in size  (i.e. the same size across devices, except for [pixel density](https://web.dev/codelab-density-descriptors/)), there is no need to set a `sizes` attribute. A `srcset` can be generated automatically from the image's width and height attributes with no further input required. 
 
 Example srcset generated: `<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x">`
 
@@ -101,12 +101,13 @@ Example srcset generated: `<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x
 
 If your image should be responsive (i.e. grow and shrink according to viewport size), then you will need to define a [`sizes` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) to generate the `srcset`.
 
-If you haven't used `sizes` before, a good place to start is to set it based on viewport width. For example, if your CSS causes the image to fill 100% of viewport width, set `sizes` to `100vw` and the browser will select the image in the `srcset` that is closest to 100% vw (after accounting for pixel density). If your image is only likely to take up half the screen (ex: in a sidebar), set `sizes` to `50vw` to ensure the browser selects a smaller image. And so on.
+If you haven't used `sizes` before, a good place to start is to set it based on viewport width. For example, if your CSS causes the image to fill 100% of viewport width, set `sizes` to `100vw` and the browser will select the image in the `srcset` that is closest to the viewport width (after accounting for pixel density). If your image is only likely to take up half the screen (ex: in a sidebar), set `sizes` to `50vw` to ensure the browser selects a smaller image. And so on.
 
-By default, these sizes are:
+If you find that the above does not cover your desired image behavior, see the documentation on [advanced sizes values](#advanced-sizes-values).
 
-`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`
+By default, the responsive breakpoints are:
 
+`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`
 
 If you would like to customize these breakpoints, you can do so using the `IMAGE_CONFIG` provider:
 
@@ -121,7 +122,7 @@ providers: [
 ],
 </code-example>
 
-If you would like to manually define a `srcset` attribute, use the `ngSrcset` attribute:
+If you would like to manually define a `srcset` attribute, you can provide your own directly, or use the `ngSrcset` attribute:
 
 <code-example format="html" language="html">
 
@@ -145,19 +146,6 @@ To disable srcset generation for a single image, you can add the `unoptimized` a
 
 &lt;img ngSrc="about.jpg" unoptimized&gt;
 
-</code-example>
-
- Alternatively, you can set the `disableAutoSrcset` property to `true` on the IMAGE_CONFIG provider:
-
-<code-example format="typescript" language="typescript">
-providers: [
-  {
-    provide: IMAGE_CONFIG,
-    useValue: {
-      disableAutoSrcset: true
-    }
-  },
-],
 </code-example>
 
 ### Disabling image lazy loading
@@ -170,6 +158,20 @@ By default, `NgOptimizedImage` sets `loading=lazy` for all images that are not m
 
 </code-example>
 
+### Advanced 'sizes' values
+
+You may want to have images displayed at varying widths on differently-sized screens. A common example of this pattern is a grid- or column-based layout that renders a single column on mobile devices, and two columns on larger devices. You can capture this behavior in the `sizes` attribute, using a "media query" syntax, such as the following:
+
+<code-example format="html" language="html">
+
+&lt;img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw"&gt;
+
+</code-example>
+
+The `sizes` attribute in the above example says "I expect this image to be 100 percent of the screen width on devices under 768px wide. Otherwise, I expect it to be 50 percent of the screen width.
+
+For additional information about the `sizes` attribute, see [web.dev](https://web.dev/learn/design/responsive-images/#sizes) or [mdn](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes).
+
 <!-- links -->
 
 <!-- external links -->