Skip to content

Commit

Permalink
Improved next/image docs around layouts. (#28345)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
leerob committed Aug 23, 2021
1 parent 00f1519 commit 8afa24f
Showing 1 changed file with 15 additions and 18 deletions.
33 changes: 15 additions & 18 deletions docs/api-reference/next/image.md
Expand Up @@ -90,29 +90,26 @@ The `<Image />` 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
Expand Down

0 comments on commit 8afa24f

Please sign in to comment.