Understand the idea

An image has more than one size: the dimensions of its file, the space it occupies in the layout, and the number of device pixels available to display it. Treating these as the same thing can send unnecessarily large files to small screens.

CSS controls the displayed size. A width-based srcset lists alternative files, while sizes describes the expected layout width. The browser combines those hints with its own conditions to choose a source. This is a choice made by the browser, not a guarantee that a specific filename will be used.

Read the example

An illustrative photograph example: supply your own three files at the stated widths, all with the same crop and aspect ratio. These filenames are not supplied assets. The downloadable gallery uses original SVG illustrations instead.

HTML · EXAMPLE
<img
  src="canal-800.jpg"
  srcset="canal-400.jpg 400w, canal-800.jpg 800w, canal-1200.jpg 1200w"
  sizes="(min-width: 889px) 800px, 90vw"
  width="1200" height="800"
  alt="A narrow canal reflecting a row of orange boats">
<!-- Matching layout: width: 90vw; max-width: 800px -->

Choose the right mechanism

  • Responsive CSS: make one image fit its container. This alone does not reduce the bytes in the file.
  • srcset and sizes: offer different resolutions of the same composition.
  • picture: offer a different crop for a layout, or a format alternative. Keep an img inside as the fallback and the location for alternative text.

Dimensions, cropping and loading

For an image that should stay proportional, a common starting point is max-width: 100% and height: auto. An intentional fixed-ratio thumbnail can use object-fit: cover, but that crops content. Check that the important subject remains visible.

Lazy loading can defer images farther down the page. Do not automatically apply it to the main image visible on arrival. A useful width and height reserve space; they do not force the displayed size when CSS overrides it.

Describe purpose, not filenames

Alternative text depends on why the image is present. Describe information the surrounding text does not already convey. A purely decorative image can have an empty alt attribute. A caption is visible context and does not automatically replace alternative text.

Follow a practical example

Build the original responsive gallery. Its vector artwork scales without separate raster sizes. Compare that simpler case with a photographic gallery before adding source variants.

A small mistake, explained

What goes wrong

Declaring 400w for a file that is actually 1200 pixels wide gives the browser incorrect information. A sizes value unrelated to the CSS can also lead to an unnecessarily large selection.

How to fix it. Inspect the actual dimensions of each file and describe the real layout slot. Include intrinsic width and height so the browser can reserve the correct aspect ratio before loading.

Try it yourself

Create two sizes of a photograph you own. Adjust the layout and inspect the selected image in browser developer tools. Repeat with a fresh load; an already cached larger image may still be used.

Further reading

MDN: Responsive images (new tab)

Original explanation and example prepared for HTML code FYI with AI assistance. Test the code in your own context. How these guides are made.