Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use width and height to describe an image’s intrinsic dimensions, CSS to control how large it appears, and sizes to tell the browser how wide a responsive image will be at different viewport widths. In next.config.js, adjust deviceSizes and imageSizes only when the defaults do not fit the widths your layout serves.
What each image-size setting controls
Next.js’s Image component extends the HTML <img> element for automatic image optimization. Its size-related props and configuration work at different stages: the component needs image dimensions to establish layout, CSS determines the displayed size, sizes describes responsive layout to the browser, and the width arrays define candidate widths available to the image optimizer.
| Setting | What it describes | Where it is set |
|---|---|---|
width and height |
The source image’s intrinsic pixel dimensions; these let the browser reserve space with the correct aspect ratio. | On the image component, unless the image is statically imported or uses fill. |
| CSS width and height | The image’s actual rendered dimensions or responsive behavior in the page layout. | Your stylesheet or component styles. |
sizes |
The image’s expected rendered width at different viewport widths, for browser candidate selection. | On the image component, especially for responsive images. |
deviceSizes |
Configured width breakpoints intended for viewport-sized images. | images in next.config.js. |
imageSizes |
Configured smaller image widths for images that provide a sizes prop. |
images in next.config.js. |
These settings are related but not interchangeable. Changing width does not make an image render at that CSS width, and changing a configuration array does not describe how wide a particular image is in your page.
Choose the right Image component pattern
Known intrinsic dimensions
When you know the source image’s pixel dimensions, pass them as width and height. Use CSS to set its displayed size. The dimensions give the browser an aspect ratio so it can reserve the image’s layout space before the file has loaded, helping reduce layout shift.
#1 Best Overall
<Image
src="/product.jpg"
alt="A product on a table"
width={1200}
height={800}
style={{ width: '100%', height: 'auto' }}
/>Here, 1200 by 800 describes the source dimensions, not a demand that the image display 1200 pixels wide. The CSS makes it responsive while retaining its aspect ratio.
Static imports
For an image imported statically, Next.js derives its width and height from the imported file. You do not need to repeat those intrinsic dimensions as props. CSS still determines its rendered size. If CSS makes it responsive, give the image an accurate sizes value as well.
Remote or dynamic URLs
A remote or dynamically chosen URL does not provide dimensions through a static import. Supply width and height so Next.js can calculate the image’s aspect ratio. If CSS changes its width across viewport sizes, also specify sizes.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Parent-controlled image box with fill
Use fill when the parent controls the image box or the intrinsic aspect ratio is not available. The parent must be positioned so the filled image has a containing box. Describe the image’s expected responsive width with sizes; otherwise the browser may assume it occupies the full viewport width.
<div className="hero">
<Image
src="/hero.jpg"
alt="A landscape"
fill
sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
style={{ objectFit: 'cover' }}
/>
</div>.hero {
position: relative;
min-height: 20rem;
}The sample sizes value is only right if the page actually uses the image at approximately full viewport width through 768 pixels, half viewport width through 1200 pixels, and one-third viewport width above that. Match the expression to your real layout rather than copying it unchanged.
Write a sizes value that matches the layout
The sizes attribute is a description of the image’s rendered width, not a CSS rule that sets that width. The browser uses the description when choosing from the responsive candidates Next.js exposes. For a responsive image, include it whenever CSS or fill changes the rendered width across viewport sizes.
Rank #3
- Find the image’s actual rendered width. Inspect the layout rules and identify the width the image occupies at each relevant breakpoint.
- Express the widths in viewport terms. Use media conditions for the breakpoint changes and a length such as
100vw,50vw, or33vwfor the corresponding image width. - Check against the rendered page. Confirm that the chosen widths reflect the layout at small, intermediate, and wide viewports. If the page uses a fixed-width content column or other layout constraint, do not claim the image occupies more space than it does.
- Keep the description aligned with CSS. When the layout changes, update
sizestoo. An inaccurate description can cause the browser to choose a candidate that does not fit the rendered width well.
If you omit sizes, the browser assumes 100vw. That may lead to an unnecessarily large download when the image actually occupies only part of the viewport. With sizes, Next.js generates a fuller width-based srcset; without it, generation is limited and is better suited to fixed-size images.
Recommended Free Tools
Configure deviceSizes and imageSizes
Change the width arrays when the documented defaults do not match the widths your layouts need. They configure available image widths; they do not replace the per-image dimensions, CSS, or accurate sizes descriptions.
deviceSizes: viewport-oriented widths
In next.config.js, set deviceSizes to the device or viewport breakpoints relevant to your site. The documented defaults are shown here:
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
module.exports = {
images: {
deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
},
}Those values are the documented default list, not a requirement to use every width or a measurement of your audience. If you customize the list, base it on the image widths your layouts actually serve rather than adding many values without a layout reason.
imageSizes: smaller image widths
Use imageSizes for smaller-than-viewport images that provide a sizes prop, such as responsive images in a narrower part of the page. The documented default list is:
Free tools Windows power users keep installed
One-click scans. No signup required.
module.exports = {
images: {
imageSizes: [32, 48, 64, 96, 128, 256, 384],
},
}Every imageSizes entry should be smaller than the smallest entry in deviceSizes. If you customize both lists, preserve that relationship.
Decide whether to customize
- Keep the defaults if they cover the widths your responsive layouts use.
- Consider changing
deviceSizeswhen your viewport-oriented image widths are poorly represented by the configured breakpoints. - Consider changing
imageSizeswhen your responsive, smaller-than-viewport images need width candidates that the current smaller-width list does not provide. - Do not try to fix a wrong
sizesdescription by changing global arrays: first make the component’s description match its actual CSS layout.
Why Next/Image may download an image that looks too large
First distinguish the file candidate from the CSS-rendered image. An image can be displayed at a modest width while the browser downloads a larger source candidate. For a responsive image, the most direct configuration issue to check is a missing or inaccurate sizes value.
- The browser assumes full viewport width. If a responsive image omits
sizes, the browser assumes100vw. Add a value that describes its real rendered width at each breakpoint. - The declared width is confused with display width.
widthandheightdescribe intrinsic dimensions and reserve aspect-ratio space. Use CSS for the displayed size. - The CSS and
sizesdisagree. If CSS makes an image half-width at a breakpoint whilesizessays100vw, correct the description to reflect the actual layout. - The wrong component pattern is being used. For a parent-controlled box, use
fill, a positioned parent, and an accuratesizesvalue. For known source dimensions, usewidthandheight. - The configured candidate widths do not suit the layout. Check whether
deviceSizesand, for smaller responsive images,imageSizescover the widths the page serves. Change them only if there is a real mismatch.
Troubleshooting image sizing
| Symptom | Likely cause | What to check or change |
|---|---|---|
| The image downloads a much wider candidate than its display width. | sizes is missing, or it describes a width larger than the CSS layout. |
Add or correct sizes to match the rendered width at each breakpoint. |
| The layout jumps when the image appears. | The browser cannot reserve the correct aspect-ratio space from the image dimensions. | For a dimensioned image, provide accurate intrinsic width and height. For fill, give the parent a controlled box. |
| The responsive image behaves like a full-width image. | The image has no useful sizes description. |
Describe its actual viewport-relative width rather than relying on the default 100vw assumption. |
A fill image has no useful visible area. |
The parent does not establish a suitable containing box. | Position the parent and give the box dimensions or other layout constraints appropriate to the page. |
| Smaller responsive images have no suitable candidates. | The smaller-width configuration may not reflect the image widths in use. | Review imageSizes, and keep all of its values below the smallest deviceSizes value. |
| Changing intrinsic props did not change the displayed width. | The rendered width is controlled by CSS. | Change the CSS layout, then align sizes with that layout if the image is responsive. |
Performance, reliability, and cost considerations
Responsive sizing is a coordination problem: CSS determines the displayed width, while sizes communicates that width to the browser so it can select an appropriate candidate. An oversized candidate can transfer more image data than the rendered layout calls for; an inaccurate description can also undermine candidate selection. The documentation cited here does not establish a universal performance percentage or benchmark, so judge the configuration against your own layout and served image widths rather than expecting a fixed savings figure.
The intrinsic dimensions serve a separate reliability purpose: they let the browser reserve the image’s aspect-ratio box ahead of loading, reducing layout shift. They are not a substitute for a correct responsive width description. Keep the responsibilities separate when debugging: layout reservation comes from dimensions or a controlled fill box, display size comes from CSS, and responsive candidate selection depends on sizes and the available configured widths.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Or skip the browser setup
If the job is to capture a page rather than build its image layout, ScreenshotNeo provides a website screenshot API. One GET request returns an image or PDF. Example using the supplied Stripe target URL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for request details. Before capture, it accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; these steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response indicates the page verdict and billing status. Its MCP server lets AI agents use screenshot tools, and 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Do I need to set both `width` and `height` for every Next.js Image?
No. Static imports provide dimensions automatically, and images using `fill` use a parent-controlled box instead.
Does `sizes` set the image’s CSS width?
No. CSS controls the rendered width; `sizes` describes it to the browser for responsive candidate selection.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
