patterntypescriptnextjsModerate
next/image: blur placeholder, priority, and sizes for performance
Viewed 0 times
Next.js 13+ (next/image v2)
next/imageprioritysizesblur placeholderLCPCLSCore Web Vitals
Error Messages
Error: Image with src X is missing required "sizes" prop — this may cause LCP issuesProblem
Pages score poorly on Core Web Vitals despite using next/image. LCP (Largest Contentful Paint) is slow because hero images are lazy-loaded. CLS (Cumulative Layout Shift) occurs because images don't reserve space. Remote images are downloaded at full resolution.
Solution
Use priority for above-the-fold images, sizes for responsive images, and placeholder for CLS:
import Image from 'next/image';
// Hero image: disable lazy loading, preload it
<Image
src='/hero.jpg'
width={1200}
height={600}
alt='Hero'
priority
quality={85}
/>
// Responsive image with correct sizes hint
<Image
src={post.cover}
fill
style={{ objectFit: 'cover' }}
sizes='(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw'
alt={post.title}
placeholder='blur'
blurDataURL={post.blurDataUrl}
/>
// Generate blurDataURL at build time:
import { getPlaiceholder } from 'plaiceholder';
const { base64 } = await getPlaiceholder('/public/photo.jpg');
import Image from 'next/image';
// Hero image: disable lazy loading, preload it
<Image
src='/hero.jpg'
width={1200}
height={600}
alt='Hero'
priority
quality={85}
/>
// Responsive image with correct sizes hint
<Image
src={post.cover}
fill
style={{ objectFit: 'cover' }}
sizes='(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw'
alt={post.title}
placeholder='blur'
blurDataURL={post.blurDataUrl}
/>
// Generate blurDataURL at build time:
import { getPlaiceholder } from 'plaiceholder';
const { base64 } = await getPlaiceholder('/public/photo.jpg');
Why
priority adds a preload link tag so browsers download hero images immediately without waiting for JavaScript. The sizes prop tells the browser which image size to download based on viewport — without it, the browser may download a 1200px image for a 300px thumbnail. placeholder='blur' prevents layout shift while the image loads.
Gotchas
- Only use priority on the 2-3 most important above-the-fold images — overusing it defeats the purpose
- sizes must match your actual CSS layout, not the image's natural dimensions
- For fill images, the parent must have position: relative and an explicit height
- Static imports (import img from './photo.jpg') automatically generate blurDataURL — remote images need it manually
Code Snippets
Responsive image with sizes hint
// Responsive image with correct sizes
<Image
src={src}
fill
sizes='(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 400px'
alt={alt}
/>Context
When optimizing images in Next.js for Core Web Vitals and performance
Revisions (0)
No revisions yet.