Accept: text/markdown header. For an index of Next.js documentation, see /docs/llms.txt.Image Component
The Next.js Image component extends the HTML <img> element for automatic image optimization.
import Image from 'next/image'\n \nexport default function Page() {\n return (\n <Image\n src=\"/profile.png\"\n width={500}\n height={500}\n alt=\"Picture of the author\"\n />\n )\n}Reference
\nProps
\nThe following props are available:
\n| Prop | Example | Type | Status |
|---|---|---|---|
src | src=\"/profile.png\" | String | Required |
alt | alt=\"Picture of the author\" | String | Required |
width | width={500} | Integer (px) | - |
height | height={500} | Integer (px) | - |
fill | fill={true} | Boolean | - |
loader | loader={imageLoader} | Function | - |
sizes | sizes=\"(max-width: 768px) 100vw, 33vw\" | String | - |
quality | quality={80} | Integer (1-100) | - |
preload | preload={true} | Boolean | - |
placeholder | placeholder=\"blur\" | String | - |
style | style={{objectFit: \"contain\"}} | Object | - |
onLoadingComplete | onLoadingComplete={img => done())} | Function | Deprecated |
onLoad | onLoad={event => done())} | Function | - |
onError | onError(event => fail()} | Function | - |
loading | loading=\"lazy\" | String | - |
blurDataURL | blurDataURL=\"data:image/jpeg...\" | String | - |
unoptimized | unoptimized={true} | Boolean | - |
overrideSrc | overrideSrc=\"/seo.png\" | String | - |
decoding | decoding=\"async\" | String | - |
src
\nThe source of the image. Can be one of the following:
\nAn internal path string.
\n<Image src=\"/profile.png\" />An absolute external URL (must be configured with remotePatterns).
\n<Image src=\"https://example.com/profile.png\" />A static import.
\nimport profile from './profile.png'\n \nexport default function Page() {\n return <Image src={profile} />\n}\n\nGood to know: For security reasons, the Image Optimization API using the default loader will not forward headers when fetching the
\nsrcimage.\nIf thesrcimage requires authentication, consider using the unoptimized property to disable Image Optimization.
alt
\nThe alt property is used to describe the image for screen readers and search engines. It is also the fallback text if images have been disabled or an error occurs while loading the image.
It should contain text that could replace the image without changing the meaning of the page. It is not meant to supplement the image and should not repeat information that is already provided in the captions above or below the image.
\nIf the image is purely decorative or not intended for the user, the alt property should be an empty string (alt=\"\").
\n\nLearn more about image accessibility guidelines.
\n
width and height
\nThe width and height properties represent the intrinsic image size in pixels. This property is used to infer the correct aspect ratio used by browsers to reserve space for the image and avoid layout shift during loading. It does not determine the rendered size of the image, which is controlled by CSS.
<Image src=\"/profile.png\" width={500} height={500} />You must set both width and height properties unless:
- \n
- The image is statically imported. \n
- The image has the
fillproperty \n
If the height and width are unknown, we recommend using the fill property.
fill
\nA boolean that causes the image to expand to the size of the parent element.
\n<Image src=\"/profile.png\" fill={true} />Positioning:
\n- \n
- The parent element must assign
position: \"relative\",\"fixed\",\"absolute\". \n - By default, the
<img>element usesposition: \"absolute\". \n
Object Fit:
\nIf no styles are applied to the image, the image will stretch to fit the container. You can use objectFit to control cropping and scaling.
- \n
\"contain\": The image will be scaled down to fit the container and preserve aspect ratio. \n\"cover\": The image will fill the container and be cropped. \n
\n\nLearn more about
\npositionandobject-fit.
loader
\nA custom function used to generate the image URL. The function receives the following parameters, and returns a URL string for the image:
\n\n'use client'\n \nimport Image from 'next/image'\n \nconst imageLoader = ({ src, width, quality }) => {\n return `https://example.com/${src}?w=${width}&q=${quality || 75}`\n}\n \nexport default function Page() {\n return (\n <Image\n loader={imageLoader}\n src=\"me.png\"\n alt=\"Picture of the author\"\n width={500}\n height={500}\n />\n )\n}\n\n\nGood to know: Using props like
\nonLoad, which accept a function, requires using Client Components to serialize the provided function.
Alternatively, you can use the loaderFile configuration in next.config.js to configure every instance of next/image in your application, without passing a prop.
sizes
\nDefine the sizes of the image at different breakpoints. Used by the browser to choose the most appropriate size from the generated srcset.
import Image from 'next/image'\n \nexport default function Page() {\n return (\n <div className=\"grid-element\">\n <Image\n fill\n src=\"/example.png\"\n sizes=\"(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw\"\n />\n </div>\n )\n}sizes should be used when:
- \n
- The image is using the
fillprop \n - CSS is used to make the image responsive \n
If sizes is missing, the browser assumes the image will be as wide as the viewport (100vw). This can cause unnecessarily large images to be downloaded.
In addition, sizes affects how srcset is generated:
- \n
- Without
sizes: Next.js generates a limitedsrcset(e.g. 1x, 2x), suitable for fixed-size images. \n - With
sizes: Next.js generates a fullsrcset(e.g. 640w, 750w, etc.), optimized for responsive layouts. \n
\n\n\n
quality
\nAn integer between 1 and 100 that sets the quality of the optimized image. Higher values increase file size and visual fidelity. Lower values reduce file size but may affect sharpness.
// Default quality is 75\n<Image quality={75} />If you’ve configured qualities in next.config.js, the value must match one of the allowed entries.
\n\nGood to know: If the original image is already low quality, setting a high quality value will increase the file size without improving appearance.
\n
style
\nAllows passing CSS styles to the underlying image element.
\nconst imageStyle = {\n borderRadius: '50%',\n border: '1px solid #fff',\n width: '100px',\n height: 'auto',\n}\n \nexport default function ProfileImage() {\n return <Image src=\"...\" style={imageStyle} />\n}\n\nGood to know: If you’re using the
\nstyleprop to set a custom width, be sure to also setheight: 'auto'to preserve the image’s aspect ratio.
preload
\nA boolean that indicates if the image should be preloaded.
\n// Default preload is false\n<Image preload={false} />- \n
true: Preloads the image by inserting a<link>in the<head>. \nfalse: Does not preload the image. \n
When to use it:
\n- \n
- The image is the Largest Contentful Paint (LCP) element. \n
- The image is above the fold, typically the hero image. \n
- You want to begin loading the image in the
<head>, before its discovered later in the<body>. \n
When not to use it:
\n- \n
- When you have multiple images that could be considered the Largest Contentful Paint (LCP) element depending on the viewport. \n
- When the
loadingproperty is used. \n - When the
fetchPriorityproperty is used. \n
In most cases, you should use loading=\"eager\" or fetchPriority=\"high\" instead of preload.
priority
\nStarting with Next.js 16, the priority property has been deprecated in favor of the preload property in order to make the behavior clear.
loading
\nControls when the image should start loading.
\n// Defaults to lazy\n<Image loading=\"lazy\" />- \n
lazy: Defer loading the image until it reaches a calculated distance from the viewport. \neager: Load the image immediately, regardless of its position in the page. \n
Use eager only when you want to ensure the image is loaded immediately.
\n\nLearn more about the
\nloadingattribute.
placeholder
\nSpecifies a placeholder to use while the image is loading, improving the perceived loading performance.
\n// defaults to empty\n<Image placeholder=\"empty\" />- \n
empty: No placeholder while the image is loading. \nblur: Use a blurred version of the image as a placeholder. Must be used with theblurDataURLproperty. \ndata:image/...: Uses the Data URL as the placeholder. \n
Examples:
\n- \n
blurplaceholder \n- Shimmer effect with data URL
placeholderprop \n - Color effect with
blurDataURLprop \n
\n\nLearn more about the
\nplaceholderattribute.
blurDataURL
\nA Data URL to\nbe used as a placeholder image before the image successfully loads. Can be automatically set or used with the placeholder=\"blur\" property.
<Image placeholder=\"blur\" blurDataURL=\"...\" />The image is automatically enlarged and blurred, so a very small image (10px or less) is recommended.
\nAutomatic
\nIf src is a static import of a jpg, png, webp, or avif file, blurDataURL is added automatically—unless the image is animated.
Manually set
\nIf the image is dynamic or remote, you must provide blurDataURL yourself. To generate one, you can use:
A large blurDataURL may hurt performance. Keep it small and simple.
\nExamples:
\n\nonLoad
\nA callback function that is invoked once the image is completely loaded and the placeholder has been removed.
\n<Image onLoad={(e) => console.log(e.target.naturalWidth)} />The callback function will be called with one argument, the event which has a target that references the underlying <img> element.
\n\nGood to know: Using props like
\nonLoad, which accept a function, requires using Client Components to serialize the provided function.
onError
\nA callback function that is invoked if the image fails to load.
\n<Image onError={(e) => console.error(e.target.id)} />\n\nGood to know: Using props like
\nonError, which accept a function, requires using Client Components to serialize the provided function.
unoptimized
\nA boolean that indicates if the image should be optimized. This is useful for images that do not benefit from optimization such as small images (less than 1KB), vector images (SVG), or animated images (GIF).
\nimport Image from 'next/image'\n \nconst UnoptimizedImage = (props) => {\n // Default is false\n return <Image {...props} unoptimized />\n}- \n
true: The source image will be served as-is from thesrcinstead of changing quality, size, or format. \nfalse: The source image will be optimized. \n
Since Next.js 12.3.0, this prop can be assigned to all images by updating next.config.js with the following configuration:
module.exports = {\n images: {\n unoptimized: true,\n },\n}overrideSrc
\nWhen providing the src prop to the <Image> component, both the srcset and src attributes are generated automatically for the resulting <img>.
<Image src=\"/profile.jpg\" /><img\n srcset=\"\n /_next/image?url=%2Fprofile.jpg&w=640&q=75 1x,\n /_next/image?url=%2Fprofile.jpg&w=828&q=75 2x\n \"\n src=\"/_next/image?url=%2Fprofile.jpg&w=828&q=75\"\n/>In some cases, it is not desirable to have the src attribute generated and you may wish to override it using the overrideSrc prop.
For example, when upgrading an existing website from <img> to <Image>, you may wish to maintain the same src attribute for SEO purposes such as image ranking or avoiding recrawl.
<Image src=\"/profile.jpg\" overrideSrc=\"/override.jpg\" /><img\n srcset=\"\n /_next/image?url=%2Fprofile.jpg&w=640&q=75 1x,\n /_next/image?url=%2Fprofile.jpg&w=828&q=75 2x\n \"\n src=\"/override.jpg\"\n/>decoding
\nA hint to the browser indicating if it should wait for the image to be decoded before presenting other content updates or not.
\n// Default is async\n<Image decoding=\"async\" />- \n
async: Asynchronously decode the image and allow other content to be rendered before it completes. \nsync: Synchronously decode the image for atomic presentation with other content. \nauto: No preference. The browser chooses the best approach. \n
\n\nLearn more about the
\ndecodingattribute.
Other Props
\nOther properties on the <Image /> component will be passed to the underlying img element with the exception of the following:
- \n
srcSet: Use Device Sizes instead. \n
Deprecated props
\nonLoadingComplete
\n\n\nWarning: Deprecated in Next.js 14, use
\nonLoadinstead.
A callback function that is invoked once the image is completely loaded and the placeholder has been removed.
\nThe callback function will be called with one argument, a reference to the underlying <img> element.
'use client'\n \n<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />\n\nGood to know: Using props like
\nonLoadingComplete, which accept a function, requires using Client Components to serialize the provided function.
Configuration options
\nYou can configure the Image Component in next.config.js. The following options are available:
localPatterns
\nUse localPatterns in your next.config.js file to allow images from specific local paths to be optimized and block all others.
module.exports = {\n images: {\n localPatterns: [\n {\n pathname: '/assets/images/**',\n search: '',\n },\n ],\n },\n}The example above will ensure the src property of next/image must start with /assets/images/ and must not have a query string. Attempting to optimize any other path will respond with 400 Bad Request error.
\n\nGood to know: Omitting the
\nsearchproperty allows all search parameters which could allow malicious actors to optimize URLs you did not intend. Try using a specific value likesearch: '?v=2'to ensure an exact match.
remotePatterns
\nUse remotePatterns in your next.config.js file to allow images from specific external paths and block all others. This ensures that only external images from your account can be served.
module.exports = {\n images: {\n remotePatterns: [new URL('https://example.com/account123/**')],\n },\n}You can also configure remotePatterns using the object:
module.exports = {\n images: {\n remotePatterns: [\n {\n protocol: 'https',\n hostname: 'example.com',\n port: '',\n pathname: '/account123/**',\n search: '',\n },\n ],\n },\n}The example above will ensure the src property of next/image must start with https://example.com/account123/ and must not have a query string. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
Wildcard Patterns:
\nWildcard patterns can be used for both pathname and hostname and have the following syntax:
- \n
*match a single path segment or subdomain \n**match any number of path segments at the end or subdomains at the beginning. This syntax does not work in the middle of the pattern. \n
module.exports = {\n images: {\n remotePatterns: [\n {\n protocol: 'https',\n hostname: '**.example.com',\n port: '',\n search: '',\n },\n ],\n },\n}This allows subdomains like image.example.com. Query strings and custom ports are still blocked.
\n\nGood to know: When omitting
\nprotocol,port,pathname, orsearchthen the wildcard**is implied. This is not recommended because it may allow malicious actors to optimize urls you did not intend.
Query Strings:
\nYou can also restrict query strings using the search property:
module.exports = {\n images: {\n remotePatterns: [\n {\n protocol: 'https',\n hostname: 'assets.example.com',\n search: '?v=1727111025337',\n },\n ],\n },\n}The example above will ensure the src property of next/image must start with https://assets.example.com and must have the exact query string ?v=1727111025337. Any other protocol or query string will respond with 400 Bad Request.
Note that any allowed remotePatterns that respond with a redirect will follow the redirect from the remote image server without validating remotePatterns again on the redirect location. You can reduce or disable redirects by configuring maximumRedirects.
loaderFile
\nloaderFiles allows you to use a custom image optimization service instead of Next.js.
module.exports = {\n images: {\n loader: 'custom',\n loaderFile: './my/image/loader.js',\n },\n}The path must be relative to the project root. The file must export a default function that returns a URL string:
\n'use client'\n \nexport default function myImageLoader({ src, width, quality }) {\n return `https://example.com/${src}?w=${width}&q=${quality || 75}`\n}Example:
\n\n\n\nAlternatively, you can use the
\nloaderprop to configure each instance ofnext/image.
path
\nIf you want to change or prefix the default path for the Image Optimization API, you can do so with the path property. The default value for path is /_next/image.
module.exports = {\n images: {\n path: '/my-prefix/_next/image',\n },\n}deviceSizes
\ndeviceSizes allows you to specify a list of device width breakpoints. These widths are used when the next/image component uses sizes prop to ensure the correct image is served for the user's device.
If no configuration is provided, the default below is used:
\nmodule.exports = {\n images: {\n deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],\n },\n}imageSizes
\nimageSizes allows you to specify a list of image widths. These widths are concatenated with the array of device sizes to form the full array of sizes used to generate image srcset.
If no configuration is provided, the default below is used:
\nmodule.exports = {\n images: {\n imageSizes: [32, 48, 64, 96, 128, 256, 384],\n },\n}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.
qualities
\nqualities allows you to specify a list of image quality values.
If not configuration is provided, the default below is used:
\nmodule.exports = {\n images: {\n qualities: [75],\n },\n}\n\nGood to know: This field is required starting with Next.js 16 because unrestricted access could allow malicious actors to optimize more qualities than you intended.
\n
You can add more image qualities to the allowlist, such as the following:
\nmodule.exports = {\n images: {\n qualities: [25, 50, 75, 100],\n },\n}In the example above, only four qualities are allowed: 25, 50, 75, and 100.
\nIf the quality prop does not match a value in this array, the closest allowed value will be used.
If the REST API is visited directly with a quality that does not match a value in this array, the server will return a 400 Bad Request response.
\nformats
\nformats allows you to specify a list of image formats to be used.
module.exports = {\n images: {\n // Default\n formats: ['image/webp'],\n },\n}Next.js automatically detects the browser's supported image formats via the request's Accept header in order to determine the best output format.
If the Accept header 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 (or the source image is animated), it will use the original image's format.
You can enable AVIF support, which will fallback to the original format of the src image if the browser does not support AVIF:
\nmodule.exports = {\n images: {\n formats: ['image/avif'],\n },\n}You can also enable both AVIF and WebP formats together. AVIF will be preferred for browsers that support it, with WebP as a fallback:
\nmodule.exports = {\n images: {\n formats: ['image/avif', 'image/webp'],\n },\n}\n\nGood to know:
\n\n
\n- We still recommend using WebP for most use cases.
\n- AVIF generally takes 50% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower, but subsequent requests that are cached will be faster.
\n- When using multiple formats, Next.js will cache each format separately. This means increased storage requirements compared to using a single format, as both AVIF and WebP versions of images will be stored for different browser support.
\n- If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the
\nAcceptheader.
minimumCacheTTL
\nminimumCacheTTL allows you to 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.
If no configuration is provided, the default below is used.
\nmodule.exports = {\n images: {\n minimumCacheTTL: 14400, // 4 hours\n },\n}You can increase the TTL to reduce the number of revalidations and potentially lower cost:
\nmodule.exports = {\n images: {\n minimumCacheTTL: 2678400, // 31 days\n },\n}The expiration (or rather Max Age) of the optimized image is defined by either the minimumCacheTTL or the upstream image Cache-Control header, whichever is larger.
If you need to change the caching behavior per image, you can configure headers to set the Cache-Control header on the upstream image (e.g. /some-asset.jpg, not /_next/image itself).
There is no mechanism to invalidate the cache at this time, so its best to keep minimumCacheTTL low. Otherwise you may need to manually change the src prop or delete the cached file <distDir>/cache/images.
disableStaticImages
\ndisableStaticImages allows you to disable static image imports.
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 = {\n images: {\n disableStaticImages: true,\n },\n}maximumRedirects
\nThe default image optimization loader will follow HTTP redirects when fetching remote images up to 3 times.
\nmodule.exports = {\n images: {\n maximumRedirects: 3,\n },\n}For your convenience, these redirects do not need to satisfy remotePatterns.
\nYou can configure the number of redirects to follow when fetching remote images. Setting the value to 0 will disable following redirects.
module.exports = {\n images: {\n maximumRedirects: 0,\n },\n}maximumDiskCacheSize
\nThe default image optimization loader will write optimized images to disk so subsequent requests can be served faster from the disk cache.
\nYou can configure the maximum disk cache size in bytes, for example 500 MB:
\nmodule.exports = {\n images: {\n maximumDiskCacheSize: 500_000_000,\n },\n}You can also disable the disk cache entirely by setting the value to 0.
module.exports = {\n images: {\n maximumDiskCacheSize: 0,\n },\n}If no value is configured, the default behavior is to check the current available disk space once during startup and use 50%.
\nWhen the disk cache exceeds the configured size, the least recently used optimized images will be deleted until the cache is under the limit again.
\nAlternatively, you can implement your own cache handler using cacheHandler which will ignore the maximumDiskCacheSize configuration.
maximumResponseBody
\nThe default image optimization loader will fetch source images up to 50 MB in size.
\nmodule.exports = {\n images: {\n maximumResponseBody: 50_000_000,\n },\n}If you know all your source images are small, you can protect memory constrained servers by reducing this to a smaller value such as 5 MB.
\nmodule.exports = {\n images: {\n maximumResponseBody: 5_000_000,\n },\n}dangerouslyAllowLocalIP
\nIn rare cases when self-hosting Next.js on a private network, you may want to allow optimizing images from local IP addresses on the same network. This is not recommended for most users because it could allow malicious users to access content on your internal network.
\nBy default, the value is false.
\nmodule.exports = {\n images: {\n dangerouslyAllowLocalIP: false,\n },\n}If you need to optimize remote images hosted elsewhere in your local network, you can set the value to true.
\nmodule.exports = {\n images: {\n dangerouslyAllowLocalIP: true,\n },\n}This might be necessary when hosting Next.js in a VPC with split-horizon DNS and you receive status 400 Bad Request. Only enable once you understand the SSRF risk.
\ndangerouslyAllowSVG
\ndangerouslyAllowSVG allows you to serve SVG images.
module.exports = {\n images: {\n dangerouslyAllowSVG: true,\n },\n}By default, Next.js does not optimize SVG images for a few reasons:
\n- \n
- SVG is a vector format meaning it can be resized losslessly. \n
- SVG has many of the same features as HTML/CSS, which can lead to vulnerabilities without proper Content Security Policy (CSP) headers. \n
We recommend using the unoptimized prop when the src prop is known to be SVG. This happens automatically when src ends with \".svg\".
<Image src=\"/my-image.svg\" unoptimized />In addition, it is strongly recommended to also set contentDispositionType to force the browser to download the image, as well as contentSecurityPolicy to prevent scripts embedded in the image from executing.
module.exports = {\n images: {\n dangerouslyAllowSVG: true,\n contentDispositionType: 'attachment',\n contentSecurityPolicy: \"default-src 'self'; script-src 'none'; sandbox;\",\n },\n}contentDispositionType
\ncontentDispositionType allows you to configure the Content-Disposition header.
module.exports = {\n images: {\n contentDispositionType: 'inline',\n },\n}contentSecurityPolicy
\ncontentSecurityPolicy allows you to configure the Content-Security-Policy header for images. This is particularly important when using dangerouslyAllowSVG to prevent scripts embedded in the image from executing.
module.exports = {\n images: {\n contentSecurityPolicy: \"default-src 'self'; script-src 'none'; sandbox;\",\n },\n}By default, the loader sets the Content-Disposition header to attachment for added protection since the API can serve arbitrary remote images.
The default value is attachment which forces the browser to download the image when visiting directly. This is particularly important when dangerouslyAllowSVG is true.
You can optionally configure inline to allow the browser to render the image when visiting directly, without downloading it.
Deprecated configuration options
\ndomains
\n\n\nWarning: Deprecated since Next.js 14 in favor of strict
\nremotePatternsin order to protect your application from malicious users.
Similar to remotePatterns, the domains configuration can be used to provide a list of allowed hostnames for external images. However, the domains configuration does not support wildcard pattern matching and it cannot restrict protocol, port, or pathname.
Since most remote image servers are shared between multiple tenants, it's safer to use remotePatterns to ensure only the intended images are optimized.
Below is an example of the domains property in the next.config.js file:
module.exports = {\n images: {\n domains: ['assets.acme.com'],\n },\n}Functions
\ngetImageProps
\nThe getImageProps function can be used to get the props that would be passed to the underlying <img> element, and instead pass them to another component, style, canvas, etc.
import { getImageProps } from 'next/image'\n \nconst { props } = getImageProps({\n src: 'https://example.com/image.jpg',\n alt: 'A scenic mountain view',\n width: 1200,\n height: 800,\n})\n \nfunction ImageWithCaption() {\n return (\n <figure>\n <img {...props} />\n <figcaption>A scenic mountain view</figcaption>\n </figure>\n )\n}This also avoid calling React useState() so it can lead to better performance, but it cannot be used with the placeholder prop because the placeholder will never be removed.
Known browser bugs
\nThis next/image component uses browser native lazy loading, which may fallback to eager loading for older browsers before Safari 15.4. When using the blur-up placeholder, older browsers before Safari 12 will fallback to empty placeholder. When using styles with width/height of auto, it is possible to cause Layout Shift on older browsers before Safari 15 that don't preserve the aspect ratio. For more details, see this MDN video.
- \n
- Safari 15 - 16.3 display a gray border while loading. Safari 16.4 fixed this issue. Possible solutions:\n
- \n
- Use CSS
@supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading=\"lazy\"] { clip-path: inset(0.6px) } }\n - Use
loading=\"eager\"if the image is above the fold \n
\n - Use CSS
- Firefox 67+ displays a white background while loading. Possible solutions:\n
- \n
- Enable AVIF
formats\n - Use
placeholder\n
\n - Enable AVIF
Examples
\nStyling images
\nStyling the Image component is similar to styling a normal <img> element, but there are a few guidelines to keep in mind:
Use className or style, not styled-jsx. In most cases, we recommend using the className prop. This can be an imported CSS Module, a global stylesheet, etc.
import styles from './styles.module.css'\n \nexport default function MyImage() {\n return <Image className={styles.image} src=\"/my-image.png\" alt=\"My Image\" />\n}You can also use the style prop to assign inline styles.
export default function MyImage() {\n return (\n <Image style={{ borderRadius: '8px' }} src=\"/my-image.png\" alt=\"My Image\" />\n )\n}When using fill, the parent element must have position: relative or display: block. This is necessary for the proper rendering of the image element in that layout mode.
<div style={{ position: 'relative' }}>\n <Image fill src=\"/my-image.png\" alt=\"My Image\" />\n</div>You cannot use styled-jsx because it's scoped to the current component (unless you mark the style as global).
Responsive images with a static export
\nWhen you import a static image, Next.js automatically sets its width and height based on the file. You can make the image responsive by setting the style:
\n![\"Responsive](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Flight%2Fresponsive-image.png&w=3840&q=75\")
![\"Responsive](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Fdark%2Fresponsive-image.png&w=3840&q=75\")
import Image from 'next/image'\nimport mountains from '../public/mountains.jpg'\n \nexport default function Responsive() {\n return (\n <div style={{ display: 'flex', flexDirection: 'column' }}>\n <Image\n alt=\"Mountains\"\n // Importing an image will\n // automatically set the width and height\n src={mountains}\n sizes=\"100vw\"\n // Make the image display full width\n // and preserve its aspect ratio\n style={{\n width: '100%',\n height: 'auto',\n }}\n />\n </div>\n )\n}Responsive images with a remote URL
\nIf the source image is a dynamic or a remote URL, you must provide the width and height props so Next.js can calculate the aspect ratio:
\nimport Image from 'next/image'\n \nexport default function Page({ photoUrl }) {\n return (\n <Image\n src={photoUrl}\n alt=\"Picture of the author\"\n sizes=\"100vw\"\n style={{\n width: '100%',\n height: 'auto',\n }}\n width={500}\n height={300}\n />\n )\n}Try it out:
\n\nResponsive image with fill
\nIf you don't know the aspect ratio of the image, you can add the fill prop with the objectFit prop set to cover. This will make the image fill the full width of its parent container.
![\"Grid](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Flight%2Ffill-container.png&w=3840&q=75\")
![\"Grid](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Fdark%2Ffill-container.png&w=3840&q=75\")
import Image from 'next/image'\nimport mountains from '../public/mountains.jpg'\n \nexport default function Fill() {\n return (\n <div\n style={{\n display: 'grid',\n gridGap: '8px',\n gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',\n }}\n >\n <div style={{ position: 'relative', width: '400px' }}>\n <Image\n alt=\"Mountains\"\n src={mountains}\n fill\n sizes=\"(min-width: 808px) 50vw, 100vw\"\n style={{\n objectFit: 'cover', // cover, contain, none\n }}\n />\n </div>\n {/* And more images in the grid... */}\n </div>\n )\n}Background Image
\nUse the fill prop to make the image cover the entire screen area:
![\"Background](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Flight%2Fbackground-image.png&w=3840&q=75\")
![\"Background](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Fdark%2Fbackground-image.png&w=3840&q=75\")
import Image from 'next/image'\nimport mountains from '../public/mountains.jpg'\n \nexport default function Background() {\n return (\n <Image\n alt=\"Mountains\"\n src={mountains}\n placeholder=\"blur\"\n quality={100}\n fill\n sizes=\"100vw\"\n style={{\n objectFit: 'cover',\n }}\n />\n )\n}For examples of the Image component used with the various styles, see the Image Component Demo.
\nRemote images
\nTo use a remote image, the src property should be a URL string.
import Image from 'next/image'\n \nexport default function Page() {\n return (\n <Image\n src=\"https://s3.amazonaws.com/my-bucket/profile.png\"\n alt=\"Picture of the author\"\n width={500}\n height={500}\n />\n )\n}Since Next.js does not have access to remote files during the build process, you'll need to provide the width, height and optional blurDataURL props manually.
The width and height attributes are used to infer the correct aspect ratio of image and avoid layout shift from the image loading in. The width and height do not determine the rendered size of the image file.
To safely allow optimizing images, define a list of supported URL patterns in next.config.js. Be as specific as possible to prevent malicious usage. For example, the following configuration will only allow images from a specific AWS S3 bucket:
module.exports = {\n images: {\n remotePatterns: [\n {\n protocol: 'https',\n hostname: 's3.amazonaws.com',\n port: '',\n pathname: '/my-bucket/**',\n search: '',\n },\n ],\n },\n}Theme detection
\nIf you want to display a different image for light and dark mode, you can create a new component that wraps two <Image> components and reveals the correct one based on a CSS media query.
.imgDark {\n display: none;\n}\n \n@media (prefers-color-scheme: dark) {\n .imgLight {\n display: none;\n }\n .imgDark {\n display: unset;\n }\n}import styles from './theme-image.module.css'\nimport Image, { ImageProps } from 'next/image'\n \ntype Props = Omit<ImageProps, 'src' | 'preload' | 'loading'> & {\n srcLight: string\n srcDark: string\n}\n \nconst ThemeImage = (props: Props) => {\n const { srcLight, srcDark, ...rest } = props\n \n return (\n <>\n <Image {...rest} src={srcLight} className={styles.imgLight} />\n <Image {...rest} src={srcDark} className={styles.imgDark} />\n </>\n )\n}\n\nGood to know: The default behavior of
\nloading=\"lazy\"ensures that only the correct image is loaded. You cannot usepreloadorloading=\"eager\"because that would cause both images to load. Instead, you can usefetchPriority=\"high\".
Try it out:
\n\nArt direction
\nIf you want to display a different image for mobile and desktop, sometimes called Art Direction, you can provide different src, width, height, and quality props to getImageProps().
import { getImageProps } from 'next/image'\n \nexport default function Home() {\n const common = { alt: 'Art Direction Example', sizes: '100vw' }\n const {\n props: { srcSet: desktop },\n } = getImageProps({\n ...common,\n width: 1440,\n height: 875,\n quality: 80,\n src: '/desktop.jpg',\n })\n const {\n props: { srcSet: mobile, ...rest },\n } = getImageProps({\n ...common,\n width: 750,\n height: 1334,\n quality: 70,\n src: '/mobile.jpg',\n })\n \n return (\n <picture>\n <source media=\"(min-width: 1000px)\" srcSet={desktop} />\n <source media=\"(min-width: 500px)\" srcSet={mobile} />\n <img {...rest} style={{ width: '100%', height: 'auto' }} />\n </picture>\n )\n}Background CSS
\nYou can even convert the srcSet string to the image-set() CSS function to optimize a background image.
import { getImageProps } from 'next/image'\n \nfunction getBackgroundImage(srcSet = '') {\n const imageSet = srcSet\n .split(', ')\n .map((str) => {\n const [url, dpi] = str.split(' ')\n return `url(\"${url}\") ${dpi}`\n })\n .join(', ')\n return `image-set(${imageSet})`\n}\n \nexport default function Home() {\n const {\n props: { srcSet },\n } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })\n const backgroundImage = getBackgroundImage(srcSet)\n const style = { height: '100vh', width: '100vw', backgroundImage }\n \n return (\n <main style={style}>\n <h1>Hello World</h1>\n </main>\n )\n}Version History
\n| Version | Changes |
|---|---|
v16.1.7 | maximumDiskCacheSize configuration added. |
v16.1.2 | maximumResponseBody configuration added. |
v16.0.0 | qualities default configuration changed to [75], preload prop added, priority prop deprecated, dangerouslyAllowLocalIP config added, maximumRedirects config added. |
v15.3.0 | remotePatterns added support for array of URL objects. |
v15.0.0 | contentDispositionType configuration default changed to attachment. |
v14.2.23 | qualities configuration added. |
v14.2.15 | decoding prop added and localPatterns configuration added. |
v14.2.14 | remotePatterns.search prop added. |
v14.2.0 | overrideSrc prop added. |
v14.1.0 | getImageProps() is stable. |
v14.0.0 | onLoadingComplete prop and domains config deprecated. |
v13.4.14 | placeholder prop support for data:/image... |
v13.2.0 | contentDispositionType configuration added. |
v13.0.6 | ref prop added. |
v13.0.0 | The next/image import was renamed to next/legacy/image. The next/future/image import was renamed to next/image. A codemod is available to safely and automatically rename your imports. <span> wrapper removed. layout, objectFit, objectPosition, lazyBoundary, lazyRoot props removed. alt is required. onLoadingComplete receives reference to img element. Built-in loader config removed. |
v12.3.0 | remotePatterns and unoptimized configuration is stable. |
v12.2.0 | Experimental remotePatterns and experimental unoptimized configuration added. layout=\"raw\" removed. |
v12.1.1 | style prop added. Experimental support for layout=\"raw\" added. |
v12.1.0 | dangerouslyAllowSVG and contentSecurityPolicy configuration added. |
v12.0.9 | lazyRoot prop added. |
v12.0.0 | formats configuration added.AVIF support added. Wrapper <div> changed to <span>. |
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. |
![\"TypeScript](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Flight%2Ftypescript-command-palette.png&w=3840&q=75\")
![\"TypeScript](\"/_next/image?url=https%3A%2F%2Fh8DxKfmAPhn8O0p3.public.blob.vercel-storage.com%2Fdocs%2Fdark%2Ftypescript-command-palette.png&w=3840&q=75\")