description |
---|
Enable Image Optimization with the built-in Image component. |
Examples
Version History
Version | Changes |
---|---|
v11.1.0 |
onLoadingComplete and lazyBoundary props added. |
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
.
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
The <Image />
component requires the following properties.
Required and must be one of the following:
- A statically imported image file, as in the example code above, or
- 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
.
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"
.
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"
.
The <Image />
component optionally accepts the following properties.
The layout behavior of the image as the viewport changes size.
layout |
Behavior | srcSet |
sizes |
---|---|---|---|
intrinsic (default) |
Scale down to fit width of container, up to image size | 1x , 2x (based on imageSizes) |
N/A |
fixed |
Sized to width and height exactly |
1x , 2x (based on imageSizes) |
N/A |
responsive |
Scale to fit width of container | 640w , 750w , ... 2048w , 3840w (based on imageSizes and deviceSizes) |
100vw |
fill |
Grow in X and Y axes to fill container | 640w , 750w , ... 2048w , 3840w (based on imageSizes and deviceSizes) |
100vw |
- Demo the
intrinsic
layout (default)- When
intrinsic
, the image will scale the dimensions down for smaller viewports, but maintain the original dimensions for larger viewports.
- When
- Demo the
fixed
layout- When
fixed
, the image dimensions will not change as the viewport changes (no responsiveness) similar to the nativeimg
element.
- When
- Demo the
responsive
layout- When
responsive
, the image will scale the dimensions down for smaller viewports and scale up for larger viewports. - Ensure the parent element uses
display: block
in their stylesheet.
- When
- Demo the
fill
layout- When
fill
, the image will stretch both width and height to the dimensions of the parent element, provided the parent element is relative. - This is usually paired with the
objectFit
property. - Ensure the parent element has
position: relative
in their stylesheet.
- When
- Demo background image
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}
/>
)
}
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.
The quality of the optimized image, an integer between 1
and 100
where 100
is the best quality. Defaults to 75
.
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
.
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.
For dynamic images, you must provide the blurDataURL
property. Solutions such as Plaiceholder can help with base64
generation.
When empty
, there will be no placeholder while the image is loading, only empty space.
Try it out:
In some cases, you may need more advanced usage. The <Image />
component
optionally accepts the following advanced properties.
The image fit when using layout="fill"
.
The image position when using layout="fill"
.
A callback function that is invoked once the image is completely loaded and the placeholder has been removed.
The onLoadingComplete
function accepts one parameter, an object with the following properties:
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.
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.
A string (with similar syntax to the margin property) that acts as the bounding box used to detect the intersection of the viewport with the image and trigger lazy loading. Defaults to "200px"
.
When true, the source image will be served as-is instead of changing quality,
size, or format. Defaults to false
.
Other properties on the <Image />
component will be passed to the underlying
img
element with the exception of the following:
style
. UseclassName
instead.srcSet
. Use Device Sizes instead.ref
. UseonLoadingComplete
instead.decoding
. It is always"async"
.
next/image
wraps the img
element with other div
elements to maintain the aspect ratio of the image and prevent Cumulative Layout Shift.
To add styles to the underlying img
element, pass the className
prop to the <Image />
component. Then, use Next.js' built-in CSS support to add rules to that class.
Note: If using layout="fill"
, ensure the parent element uses position: relative
.
For more information on what to do next, we recommend the following sections: