Guides
How to Optimize Next.js Images
next/image handles resizing, format conversion, and lazy loading automatically, but it needs correct configuration — especially for images served from an external domain like a CMS or CDN.
Prerequisites
- arrow_rightA Next.js project
- arrow_rightImage assets, either local or from a remote source (CMS, CDN)
Step 1: Basic Usage With Local Images
import Image from 'next/image';
import hero from './hero.jpg';
<Image src={hero} alt="Product hero shot" />Importing a local image gives Next.js its dimensions automatically, so width and height don't need to be set manually.
Step 2: Configure Remote Images
next.config.js
module.exports = {
images: {
remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com' }],
},
};Remote images need explicit width and height props since Next.js can't read the file's dimensions ahead of time, and the hostname must be allow-listed in next.config.js for security.
Step 3: Use Priority for the LCP Image Only
Set priority on the single largest above-the-fold image to preload it; every other image should lazy-load by default, which is next/image's out-of-the-box behavior.
Common Errors
- arrow_right"hostname not configured" error — the remote domain isn't listed in remotePatterns
- arrow_rightLayout shift despite using next/image — width/height (or fill with a sized parent) missing on a remote image
- arrow_rightImages look blurry — check the sizes prop is set correctly for responsive layouts so the right resolution is requested
Performance Considerations
- arrow_rightUse priority sparingly — only the actual LCP image
- arrow_rightSet sizes accurately for responsive images so the browser doesn't request a larger file than needed
- arrow_rightPrefer modern formats — next/image serves WebP/AVIF automatically where the browser supports it
Frequently Asked Questions
Do I need to manually convert images to WebP?add
No — next/image serves an optimized, modern format automatically based on the requesting browser's support, without a manual conversion step.
Why does a remote image need explicit width and height?add
Next.js can read dimensions from local imported files automatically, but has no way to inspect a remote file's dimensions ahead of render, so they must be provided explicitly to reserve the correct layout space.
What does the fill prop do?add
It makes the image expand to fill its parent container, useful for responsive layouts where the image's size should match a container rather than fixed pixel dimensions — the parent needs position: relative.