Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update image documentation for static image #25949

Merged
merged 9 commits into from
Jun 15, 2021
Merged

Update image documentation for static image #25949

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d2d763a
Update image documentation for static image
atcastle Jun 9, 2021
1ad0c75
Update docs/api-reference/next/image.md
atcastle Jun 9, 2021
3cc1612
Update docs/api-reference/next/image.md
atcastle Jun 9, 2021
15dcdc3
Update docs/api-reference/next/image.md
atcastle Jun 9, 2021
0b16b4e
Update docs/api-reference/next/image.md
atcastle Jun 9, 2021
992258c
Version history and placeholder revisions
atcastle Jun 9, 2021
6591942
Apply suggestions from code review
ijjk Jun 15, 2021
2436f3c
Merge branch 'canary' into patch-1
ijjk Jun 15, 2021
7cae558
lint-fix
ijjk Jun 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 34 additions & 11 deletions docs/api-reference/next/image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,12 @@ description: Enable Image Optimization with the built-in Image component.
<details>
<summary><b>Version History</b></summary>

| 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` | Static image support and blur placeholder added. |
atcastle marked this conversation as resolved.
Show resolved Hide resolved
| `v10.0.5` | `loader` prop added. |
| `v10.0.1` | `layout` prop added. |
| `v10.0.0` | `next/image` introduced. |

</details>

Expand All @@ -39,16 +40,15 @@ We can serve an optimized image like so:

```jsx
import Image from 'next/image'
import profilePic from '../me.png'

function Home() {
return (
<>
<h1>My Homepage</h1>
<Image
src="/me.png"
src={profilePic}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we show code examples of:

  • Static Image
  • Dynamic src (fetching from a CMS)
    • Manually adding blurDataURL example?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps, it could get busy.

We also need to update these pages:

https://nextjs.org/docs/basic-features/image-optimization
https://nextjs.org/docs/basic-features/static-file-serving

alt="Picture of the author"
width={500}
height={500}
/>
<p>Welcome to my homepage!</p>
</>
Expand All @@ -64,7 +64,12 @@ The `<Image />` component requires the following properties.

### src

The path or URL to the source image. This is required.
Can be either:
1) A statically imported image file, as in the example code above, or
2) A path to a remotely hosted image. This can be either an absolute URL,
or a relative path to be used with a [loader.](/docs/basic-features/image-optimization.md#loader)

This is required.
atcastle marked this conversation as resolved.
Show resolved Hide resolved

When using an external URL, you must add it to
[domains](/docs/basic-features/image-optimization.md#domains) in
Expand All @@ -74,13 +79,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

Expand Down Expand Up @@ -162,6 +167,15 @@ 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

ijjk marked this conversation as resolved.
Show resolved Hide resolved
Setting `placeholder="blur"` enables an automatic placeholder effect for the image,
which is rendered on the page until the image is fully loaded.

Blurry placeholder images are generated automatically for **statically imported** images.
atcastle marked this conversation as resolved.
Show resolved Hide resolved
If you wish to use `placeholder="blur"` with any other image, you must provide a value for
the [`blurDataURL` property](#blurDataURL).
atcastle marked this conversation as resolved.
Show resolved Hide resolved

## Advanced Props

In some cases, you may need more advanced usage. The `<Image />` component
Expand Down Expand Up @@ -196,6 +210,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
atcastle marked this conversation as resolved.
Show resolved Hide resolved
be used as a placeholder image while the final image loads. Only has any effect when combined
atcastle marked this conversation as resolved.
Show resolved Hide resolved
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,
Expand Down