From 8873374963fdd116ab7a7e537c9604c7912f6a95 Mon Sep 17 00:00:00 2001 From: Alex Castle Date: Tue, 15 Jun 2021 07:40:37 -0700 Subject: [PATCH] Update image documentation for static image (#25949) * Update image documentation for static image Adds documentation for static image and blurry placeholder functionality * Update docs/api-reference/next/image.md Co-authored-by: Steven * Update docs/api-reference/next/image.md Co-authored-by: Steven * Update docs/api-reference/next/image.md Co-authored-by: Steven * Update docs/api-reference/next/image.md Co-authored-by: Steven * Version history and placeholder revisions * Apply suggestions from code review Co-authored-by: Steven * lint-fix Co-authored-by: Steven Co-authored-by: JJ Kasper --- docs/api-reference/next/image.md | 43 +++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md index 2a075daf5b44e..a67e29c87059e 100644 --- a/docs/api-reference/next/image.md +++ b/docs/api-reference/next/image.md @@ -14,11 +14,12 @@ description: Enable Image Optimization with the built-in Image component.
Version History -| Version | Changes | -| --------- | ------------------------ | -| `v10.0.5` | `loader` prop added. | -| `v10.0.1` | `layout` prop added. | -| `v10.0.0` | `next/image` introduced. | +| Version | Changes | +| --------- | ---------------------------------------------------------------------------- | +| `v11.0.0` | Added static imports for `src`. Added `placeholder` and `blurDataURL` props. | +| `v10.0.5` | `loader` prop added. | +| `v10.0.1` | `layout` prop added. | +| `v10.0.0` | `next/image` introduced. |
@@ -39,17 +40,13 @@ We can serve an optimized image like so: ```jsx import Image from 'next/image' +import profilePic from '../me.png' function Home() { return ( <>

My Homepage

- Picture of the author + Picture of the author

Welcome to my homepage!

) @@ -64,7 +61,11 @@ The `` component requires the following properties. ### src -The path or URL to the source image. This is required. +Required and must be one of the following: + +1. A statically imported image file, as in the example code above, or +2. A path string. This can be either an absolute external URL, + or an internal path depending on the [loader](#loader). When using an external URL, you must add it to [domains](/docs/basic-features/image-optimization.md#domains) in @@ -74,13 +75,13 @@ When using an external URL, you must add it to The width of the image, in pixels. Must be an integer without a unit. -Required unless [`layout="fill"`](#layout). +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. -Required unless [`layout="fill"`](#layout). +Required, except for statically imported images, or those with [`layout="fill"`](#layout). ## Optional Props @@ -162,6 +163,11 @@ When true, the image will be considered high priority and Should only be used when the image is visible above the fold. Defaults to `false`. +### placeholder + +A placeholder to use while the image is loading, possible values are `blur` or `empty`. Defaults to `empty`. +When `placeholder="blur"`, the `blurDataURL` will be used as the placeholder. If the `src` is an object from a static import, then `blurDataURL` will automatically be populated. If the `src` is a string, then you must provide the [`blurDataURL` property](#blurdataurl). + ## Advanced Props In some cases, you may need more advanced usage. The `` component @@ -196,6 +202,15 @@ When `eager`, load the image immediately. [Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading) +### blurDataURL + +A [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) to +be used as a placeholder image before the `src` image successfully loads. Only takes effect when combined +with [`placeholder="blur"`](#placeholder). + +Must be a base64-encoded image. It will be enlarged and blurred, so a very small image (10px or +less) is recommended. Including larger images as placeholders may harm your application performance. + ### unoptimized When true, the source image will be served as-is instead of changing quality,