Skip to content

Latest commit

 

History

History
254 lines (168 loc) · 7.98 KB

image.md

File metadata and controls

254 lines (168 loc) · 7.98 KB
description
Enable Image Optimization with the built-in Image component.

next/image

Examples
Version History
Version Changes
v11.0.0 src prop support for static import.
placeholder prop added.
blurDataURL prop added.
v10.0.5 loader prop added.
v10.0.1 layout prop added.
v10.0.0 next/image introduced.

Before moving forward, we recommend you to read Image Optimization first.

Image Optimization can be enabled via the <Image /> component exported by next/image.

Usage

For an example, consider a project with the following files:

  • pages/index.js
  • public/me.png

We can serve an optimized image like so:

import Image from 'next/image'
import profilePic from '../public/me.png'

function Home() {
  return (
    <>
      <h1>My Homepage</h1>
      <Image src={profilePic} alt="Picture of the author" />
      <p>Welcome to my homepage!</p>
    </>
  )
}

export default Home

Required Props

The <Image /> component requires the following properties.

src

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.

When using an external URL, you must add it to domains in next.config.js.

width

The width of the image, in pixels. Must be an integer without a unit.

Required, except for statically imported images, or those with layout="fill".

height

The height of the image, in pixels. Must be an integer without a unit.

Required, except for statically imported images, or those with layout="fill".

Optional Props

The <Image /> component optionally accepts the following properties.

layout

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 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 fill, the image will stretch both width and height to the dimensions of the parent element, usually paired with the objectFit property.

Try it out:

loader

A custom function used to resolve URLs. Defaults to images object in next.config.js.

loader is a function returning a string, given the following parameters:

import Image from 'next/image'

const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

A string mapping media queries to device sizes. Defaults to 100vw.

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.

quality

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.

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 blur, the blurDataURL property will be used as the placeholder. If src is an object from a static import and the imported image is jpg, png, or webp, then blurDataURL will automatically be populated. Otherwise you must provide the blurDataURL property.

When empty, there will be no placeholder while the image is loading, only empty space.

Try it out:

Advanced Props

In some cases, you may need more advanced usage. The <Image /> component optionally accepts the following advanced properties.

objectFit

The image fit when using layout="fill".

Learn more

objectPosition

The image position when using layout="fill".

Learn more

loading

Attention: This property is only meant for advanced usage. Switching an image to load with eager will normally hurt performance.

We recommend using the 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 eager, load the image immediately.

Learn more

blurDataURL

A Data URL to be used as a placeholder image before the src image successfully loads. Only takes effect when combined with placeholder="blur".

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.

Try it out:

You can also generate a solid color Data URL to match the image.

unoptimized

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:

  • style. Use className instead.
  • srcSet. Use Device Sizes instead.
  • decoding. It is always "async".

Related

For more information on what to do next, we recommend the following sections: