From 8afa24fca53aa14e1668112bcc30a845d30a7bd7 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Mon, 23 Aug 2021 12:39:19 -0500 Subject: [PATCH] Improved `next/image` docs around layouts. (#28345) There's been community feedback the `layouts` section of `next/image` docs could be improved. Thanks to this great article (https://blog.eyas.sh/2021/08/gatsby-to-next-js/), I've added a helpful table here giving a high-level overview, as well as re-organized the `layout` section to be more helpful. --- docs/api-reference/next/image.md | 33 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 05b53dedb83a..b093a8d1598b 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -90,29 +90,26 @@ The `` component optionally accepts the following properties. ### layout -The layout behavior of the image as the viewport changes size. Defaults to -`intrinsic`. +The layout behavior of the image as the viewport changes size. -When `fixed`, the image dimensions will not change as the viewport changes (no -responsiveness) similar to the native `img` element. - -When `intrinsic`, the image will scale the dimensions down for smaller viewports -but maintain the original dimensions for larger viewports. - -When `responsive`, the image will scale the dimensions down for smaller -viewports and scale up for larger viewports. -Note: the responsive layout may not work correctly if the parent element uses a display value other than `block` such as `display: flex` or `display: grid`. - -When `fill`, the image will stretch both width and height to the dimensions of -the parent element, provided the parent element is relative. This is usually paired with the [`objectFit`](#objectFit) property. -Ensure the parent element has `position: relative` in their stylesheet. - -Try it out: +| `layout` | Behavior | `srcSet` | `sizes` | +| --------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `intrinsic` (default) | Scale *down* to fit width of container, up to image size | `1x`, `2x` (based on [imageSizes](/docs/basic-features/image-optimization.md#image-sizes)) | N/A | +| `fixed` | Sized to `width` and `height` exactly | `1x`, `2x` (based on [imageSizes](/docs/basic-features/image-optimization.md#image-sizes)) | N/A | +| `responsive` | Scale to fit width of container | `640w`, `750w`, ... `2048w`, `3840w` (based on [imageSizes](/docs/basic-features/image-optimization.md#image-sizes) and [deviceSizes](/docs/basic-features/image-optimization.md#device-sizes)) | `100vw` | +| `fill` | Grow in X and Y axes to fill container | `640w`, `750w`, ... `2048w`, `3840w` (based on [imageSizes](/docs/basic-features/image-optimization.md#image-sizes) and [deviceSizes](/docs/basic-features/image-optimization.md#device-sizes)) | `100vw` | +- [Demo the `intrinsic` layout (default)](https://image-component.nextjs.gallery/layout-intrinsic) + - When `intrinsic`, the image will scale the dimensions down for smaller viewports, but maintain the original dimensions for larger viewports. - [Demo the `fixed` layout](https://image-component.nextjs.gallery/layout-fixed) -- [Demo the `intrinsic` layout](https://image-component.nextjs.gallery/layout-intrinsic) + - When `fixed`, the image dimensions will not change as the viewport changes (no responsiveness) similar to the native `img` element. - [Demo the `responsive` layout](https://image-component.nextjs.gallery/layout-responsive) + - When `responsive`, the image will scale the dimensions down for smaller viewports and scale up for larger viewports. + - Ensure the parent element uses `display: block` in their stylesheet. - [Demo the `fill` layout](https://image-component.nextjs.gallery/layout-fill) + - When `fill`, the image will stretch both width and height to the dimensions of the parent element, provided the parent element is relative. + - This is usually paired with the [`objectFit`](#objectFit) property. + - Ensure the parent element has `position: relative` in their stylesheet. - [Demo background image](https://image-component.nextjs.gallery/background) ### loader