Unverified Commit 74693810 authored by Joe Haddad's avatar Joe Haddad Committed by GitHub

docs: update image docs for consistency (#20621)

parent 45b87aa2
......@@ -13,7 +13,7 @@ description: Enable Image Optimization with the built-in Image component.
<details>
<summary><b>Version History</b></summary>
| Version | Changes |
| --------- | ------------------------ |
| `v10.0.1` | `layout` prop added. |
......@@ -21,9 +21,11 @@ description: Enable Image Optimization with the built-in Image component.
</details>
> Before moving forward, we recommend you to read [Image Optimization](/docs/basic-features/image-optimization.md) first.
> Before moving forward, we recommend you to read
> [Image Optimization](/docs/basic-features/image-optimization.md) first.
Image Optimization can be enabled via the `Image` component exported by `next/image`.
Image Optimization can be enabled via the `<Image />` component exported by
`next/image`.
## Usage
......@@ -57,41 +59,49 @@ export default Home
## Required Props
The `Image` component requires the following properties.
The `<Image />` component requires the following properties.
### src
The path or URL to the source image. This is required.
When using an external URL, you must add it to [domains](/docs/basic-features/image-optimization.md#domains) in `next.config.js`.
When using an external URL, you must add it to
[domains](/docs/basic-features/image-optimization.md#domains) in
`next.config.js`.
### width
The width of the image, in pixels. Must be an integer without a unit.
Required unless [layout="fill"`](#layout).
Required unless [`layout="fill"`](#layout).
### height
The height of the image, in pixels. Must be an integer without a unit.
Required unless [layout="fill"`](#layout).
Required unless [`layout="fill"`](#layout).
## Optional Props
The `Image` component optionally accepts the following properties.
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. Defaults to
`intrinsic`.
When `fixed`, the image dimensions will not change as the viewport changes (no responsiveness) similar to the native `img` element.
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 `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.
When `responsive`, the image will scale the dimensions down for smaller
viewports and scale up for larger viewports.
When `fill`, the image will stretch both width and height to the dimensions of the parent element, usually paired with [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit).
When `fill`, the image will stretch both width and height to the dimensions of
the parent element, usually paired with
[object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit).
Try it out:
......@@ -105,23 +115,27 @@ Try it out:
A string mapping media queries to device sizes. Defaults to `100vw`.
We recommend setting `sizes` when `layout="responsive"` and your image will not be the same width as the viewport.
We recommend setting `sizes` when using `layout="responsive"` or `layout="fill"` and your image will **not** be the same width as the viewport.
[Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
### quality
The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality. Defaults to 75.
The quality of the optimized image, an integer between `1` and `100` where `100`
is the best quality. Defaults to `75`.
### priority
When true, the image will be considered high priority and [preload](https://web.dev/preload-responsive-images/).
When true, the image will be considered high priority and
[preload](https://web.dev/preload-responsive-images/).
Should only be used when the image is visible above the fold. Defaults to false.
Should only be used when the image is visible above the fold. Defaults to
`false`.
## Advanced Props
In some cases, you may need more advanced usage. The `Image` component optionally accepts the following advanced properties.
In some cases, you may need more advanced usage. The `<Image />` component
optionally accepts the following advanced properties.
### objectFit
......@@ -140,12 +154,13 @@ The image position when using `layout="fill"`.
> **Attention**: This property is only meant for advanced usage. Switching an
> image to load with `eager` will normally **hurt performance**.
>
> You are probably looking for the [`priority`](#priority) property instead,
> which properly loads the image eagerly for nearly all use cases.
> We recommend using the [`priority`](#priority) property instead, which
> properly loads the image eagerly for nearly all use cases.
The loading behavior of the image. Defaults to `lazy`.
When `lazy`, defer loading the image until it reaches a calculated distance from the viewport.
When `lazy`, defer loading the image until it reaches a calculated distance from
the viewport.
When `eager`, load the image immediately.
......@@ -153,14 +168,18 @@ When `eager`, load the image immediately.
### unoptimized
When true, the source image will be served as-is instead of changing quality, size, or format. Defaults to `false`.
When true, the source image will be served as-is instead of changing quality,
size, or format. Defaults to `false`.
## Other Props
Other properties on the `Image` component will be passed to the underlying `img` element with the exception of the following:
Other properties on the `<Image />` component will be passed to the underlying
`img` element with the exception of the following:
- `style`. Use `className` instead.
- `srcSet`. Use [Device Sizes](/docs/basic-features/image-optimization.md#device-sizes) instead.
- `srcSet`. Use
[Device Sizes](/docs/basic-features/image-optimization.md#device-sizes)
instead.
- `decoding`. It is always `"async"`.
## Related
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment