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. ...@@ -13,7 +13,7 @@ description: Enable Image Optimization with the built-in Image component.
<details> <details>
<summary><b>Version History</b></summary> <summary><b>Version History</b></summary>
| Version | Changes | | Version | Changes |
| --------- | ------------------------ | | --------- | ------------------------ |
| `v10.0.1` | `layout` prop added. | | `v10.0.1` | `layout` prop added. |
...@@ -21,9 +21,11 @@ description: Enable Image Optimization with the built-in Image component. ...@@ -21,9 +21,11 @@ description: Enable Image Optimization with the built-in Image component.
</details> </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 ## Usage
...@@ -57,41 +59,49 @@ export default Home ...@@ -57,41 +59,49 @@ export default Home
## Required Props ## Required Props
The `Image` component requires the following properties. The `<Image />` component requires the following properties.
### src ### src
The path or URL to the source image. This is required. 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 ### width
The width of the image, in pixels. Must be an integer without a unit. 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 ### height
The height of the image, in pixels. Must be an integer without a unit. 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 ## Optional Props
The `Image` component optionally accepts the following properties. The `<Image />` component optionally accepts the following properties.
### layout ### 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: Try it out:
...@@ -105,23 +115,27 @@ Try it out: ...@@ -105,23 +115,27 @@ Try it out:
A string mapping media queries to device sizes. Defaults to `100vw`. 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). [Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
### quality ### 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 ### 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 ## 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 ### objectFit
...@@ -140,12 +154,13 @@ The image position when using `layout="fill"`. ...@@ -140,12 +154,13 @@ The image position when using `layout="fill"`.
> **Attention**: This property is only meant for advanced usage. Switching an > **Attention**: This property is only meant for advanced usage. Switching an
> image to load with `eager` will normally **hurt performance**. > image to load with `eager` will normally **hurt performance**.
> >
> You are probably looking for the [`priority`](#priority) property instead, > We recommend using the [`priority`](#priority) property instead, which
> which properly loads the image eagerly for nearly all use cases. > properly loads the image eagerly for nearly all use cases.
The loading behavior of the image. Defaults to `lazy`. 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. When `eager`, load the image immediately.
...@@ -153,14 +168,18 @@ When `eager`, load the image immediately. ...@@ -153,14 +168,18 @@ When `eager`, load the image immediately.
### unoptimized ### 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 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. - `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"`. - `decoding`. It is always `"async"`.
## Related ## 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