Responsive images with srcset and sizes

Why srcset

A single image cannot serve a phone and a large desktop well. A 1200px-wide image pushed to mobile costs bandwidth and shrinks the perceived speed. srcset lets the browser choose between several files based on viewport size and device pixel ratio, so a phone downloads the small file and a retina desktop downloads the big one.

srcset basics

<img
  src="photo-800.jpg"
  srcset="photo-400.jpg 400w, photo-800.jpg 800w, photo-1200.jpg 1200w"
  sizes="(max-width: 600px) 100vw, 50vw"
  alt="A mountain lake at sunset">

The w descriptors (400w, 800w, 1200w) tell the browser the intrinsic width of each file. The sizes attribute tells the browser how wide the image will be rendered at each breakpoint, in viewport widths (vw) or pixels. Together the browser picks the smallest file that fits its viewport and device pixel ratio.

Always include src as the fallback for browsers without srcset support and for crawlers that read only the plain src.

The sizes attribute

sizes is required for w descriptors to work well. If you omit it, the browser assumes the image renders full viewport width, 100vw, and downloads too-large files. Sizes can be written in the same syntax as a width query:

sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"

For a fixed-width image, use pixels: sizes="450px". The value should match the width the CSS actually applies, not a guess. Mismatches are the most common cause of oversized downloads.

Art direction with picture

When the image itself must change (a square crop on mobile, a wide crop on desktop), srcset alone is not enough. Use picture with source elements and a media attribute:

<picture>
  <source media="(max-width: 600px)" srcset="photo-mobile.jpg">
  <source media="(min-width: 601px)" srcset="photo-desktop.jpg">
  <img src="photo-fallback.jpg" alt="A mountain lake at sunset">
</picture>

The img inside picture holds the fallback and the accessibility attributes. Keep alt on the img, never on the source.

Pitfalls

• Do not write sizes as a fixed percentage guess when the CSS uses different rules. This typically doubles download weight.
• Do not forget to update the files themselves. srcset only helps if the candidate files really are different sizes.
• Do not use srcset for art direction; that is what picture is for.
• Do not lazy-load the hero. Keep hero images eager with fetchpriority="high" so LCP is not delayed.
• Do use the same alt on every variant of one image, because the variants are one image, not separate ones.

Verify

In dev tools, open the Network tab on a narrow viewport and confirm the requested image is the small candidate, then widen and confirm the big candidate is requested. If the same large file appears on both, either sizes or the file set is wrong.