diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 4fa36b777d21..a1936484cf38 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -47,13 +47,13 @@ When using an external URL, you must add it to ### width -The width of the image, in pixels. Must be an integer without a unit. +The desired width of the rendered image, in pixels. Must be an integer without a unit. Required, except for statically imported images, or those with [`layout="fill"`](#layout). ### height -The height of the image, in pixels. Must be an integer without a unit. +The desired height of the rendered image, in pixels. Must be an integer without a unit. Required, except for statically imported images, or those with [`layout="fill"`](#layout). diff --git a/docs/basic-features/image-optimization.md b/docs/basic-features/image-optimization.md index 0c7cb5a6a292..b18744188d24 100644 --- a/docs/basic-features/image-optimization.md +++ b/docs/basic-features/image-optimization.md @@ -150,7 +150,7 @@ One of the ways that images most commonly hurt performance is through _layout sh Because `next/image` is designed to guarantee good performance results, it cannot be used in a way that will contribute to layout shift, and **must** be sized in one of three ways: 1. Automatically, using a [static import](#local-images) -2. Explicitly, by including a `height` **and** `width` property +2. Explicitly, by including the desired `height` **and** `width` property 3. Implicitly, by using `layout="fill"` which causes the image to expand to fill its parent element. > ### What if I don't know the size of my images? @@ -163,11 +163,11 @@ Because `next/image` is designed to guarantee good performance results, it canno > > **Normalize your images** > -> If you're serving images from a source that you control, consider modifying your image pipeline to normalize the images to a specific size. +> If you're serving images from a source that you control, consider modifying your image pipeline to normalize the images to a specific size. For example, a user-provided avatar image could be cropped before being saved and then the image size would be known by the time its rendered. > > **Modify your API calls** > -> If your application is retrieving image URLs using an API call (such as to a CMS), you may be able to modify the API call to return the image dimensions along with the URL. +> If your application is retrieving image URLs using an API call (such as to a CMS), you may be able to modify the API call to return the image dimensions along with the URL. For example, set the [`loader`](/docs/api-reference/next/image.md#loader) property to match the API call expected by your CMS. If none of the suggested methods works for sizing your images, the `next/image` component is designed to work well on a page alongside standard `` elements.