description |
---|
Enable Image Optimization with the built-in Image component. |
Examples
Version History
Version | Changes |
---|---|
v12.0.0 |
formats configuration added as well as AVIF support. |
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. |
Note: This is API documentation for the Image Component and Image Optimization. For a feature overview and usage information for images in Next.js, please see Images.
The <Image />
component requires the following properties.
Must be one of the following:
- A statically imported image file, 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 accepts a number of additional properties beyond those which are required. This section describes the most commonly-used properties of the Image component. Find details about more rarely-used properties in the Advanced Props section.
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 both 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. Setting the loader as a prop on the Image component overrides the default loader defined in the images
section of next.config.js
.
A loader
is a function returning a URL string for the image, given the following parameters:
Here is an example of using a custom loader with next/image
:
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 that provides information about how wide the image will be at different breakpoints. Defaults to 100vw
(the full width of the screen) when using layout="responsive"
or layout="fill"
.
sizes
is important for performance when using layout="responsive"
or layout="fill"
with images that take up less than the full viewport width.
If you are using layout="fill"
or layout="responsive"
and the image will always be less than half the viewport width, include sizes="50vw"
. Without sizes
, the image will be sent at twice the necessary resolution, decreasing performance.
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. Lazy loading is automatically disabled for images using priority
.
You should use the priority
attribute on any image which you suspect will be the Largest Contentful Paint (LCP) element. It may be appropriate to have multiple priority images, as different images may be the LCP element for different viewport sizes.
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
, .webp
, or .avif
, then blurDataURL
will be automatically 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.
Defines how the image will fit into its parent container when using layout="fill"
.
This value is passed to the object-fit CSS property for the src
image.
Defines how the image is positioned within its parent element when using layout="fill"
.
This value is passed to the object-position CSS property applied to the image.
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"
.
To protect your application from malicious users, you must define a list of image provider domains that you want to be served from the Next.js Image Optimization API. This is configured in with the domains
property in your next.config.js
file, as shown below:
module.exports = {
images: {
domains: ['assets.acme.com'],
},
}
If you want to use a cloud provider to optimize images instead of using the Next.js built-in Image Optimization API, you can configure the loader
and path
prefix in your next.config.js
file. This allows you to use relative URLs for the Image src
and automatically generate the correct absolute URL for your provider.
module.exports = {
images: {
loader: 'imgix',
path: 'https://example.com/myaccount/',
},
}
The following Image Optimization cloud providers are included:
- Default: Works automatically with
next dev
,next start
, or a custom server - Vercel: Works automatically when you deploy on Vercel, no configuration necessary. Learn more
- Imgix:
loader: 'imgix'
- Cloudinary:
loader: 'cloudinary'
- Akamai:
loader: 'akamai'
- Custom:
loader: 'custom'
use a custom cloud provider by implementing theloader
prop on thenext/image
component
If you need a different provider, you can use the loader
prop with next/image
.
The
next/image
component's default loader is not supported when usingnext export
. However, other loader options will work.
The
next/image
component's default loader usessquoosh
because it is quick to install and suitable for a development environment. When usingnext start
in your production environment, it is strongly recommended that you installsharp
by runningyarn add sharp
in your project directory. This is not necessary for Vercel deployments, assharp
is installed automatically.
The following configuration is for advanced use cases and is usually not necessary. If you choose to configure the properties below, you will override any changes to the Next.js defaults in future updates.
If you know the expected device widths of your users, you can specify a list of device width breakpoints using the deviceSizes
property in next.config.js
. These widths are used when the next/image
component uses layout="responsive"
or layout="fill"
to ensure the correct image is served for user's device.
If no configuration is provided, the default below is used.
module.exports = {
images: {
deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
},
}
You can specify a list of image widths using the images.imageSizes
property in your next.config.js
file. These widths are concatenated with the array of device sizes to form the full array of sizes used to generate image srcsets.
The reason there are two seperate lists is that imageSizes is only used for images which provide a sizes
prop, which indicates that the image is less than the full width of the screen. Therefore, the sizes in imageSizes should all be smaller than the smallest size in deviceSizes.
If no configuration is provided, the default below is used.
module.exports = {
images: {
imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
},
}
The following describes the caching algorithm for the default loader. For all other loaders, please refer to your cloud provider's documentation.
Images are optimized dynamically upon request and stored in the <distDir>/cache/images
directory. The optimized image file will be served for subsequent requests until the expiration is reached. When a request is made that matches a cached but expired file, the cached file is deleted before generating a new optimized image and caching the new file.
The expiration (or rather Max Age) is defined by the upstream server's Cache-Control
header.
- If
s-maxage
is found inCache-Control
, it is used. If nos-maxage
is found, thenmax-age
is used. If nomax-age
is found, thenminimumCacheTTL
is used. - You can configure
minimumCacheTTL
to increase the cache duration when the upstream image does not includemax-age
. - You can also configure
deviceSizes
andimageSizes
to reduce the total number of possible generated images. - You can also configure formats to disable multiple formats in favor of a single image format.
You can configure the Time to Live (TTL) in seconds for cached optimized images. In many cases, it's better to use a Static Image Import which will automatically hash the file contents and cache the image forever with a Cache-Control
header of immutable
.
module.exports = {
images: {
minimumCacheTTL: 60,
},
}
If you need to add a Cache-Control
header for the browser (not recommended), you can configure headers
on the upstream image e.g. /some-asset.jpg
not /_next/image
itself.
The default behavior allows you to import static files such as import icon from './icon.png
and then pass that to the src
property.
In some cases, you may wish to disable this feature if it conflicts with other plugins that expect the import to behave differently.
You can disable static image imports inside your next.config.js
:
module.exports = {
images: {
disableStaticImages: true,
},
}
The default Image Optimization API will automatically detect the browser's supported image formats via the request's Accept
header.
If the Accept
matches more than one of the configured formats, the first match in the array is used. Therefore, the array order matters. If there is no match, the Image Optimization API will fallback to the original image's format.
If no configuration is provided, the default below is used.
module.exports = {
images: {
formats: ['image/avif', 'image/webp'],
},
}
For an overview of the Image component features and usage guidelines, see: