HTML Tutorial / Responsive Images: srcset, sizes, and picture

Responsive images offer a browser files with different resolutions or compositions so it can choose one suited to the display. Use srcset and sizes for resolution choices of the same image, and picture when a narrower screen needs a different crop.

Get the example image files

These examples use the same lake photo at three widths and a square crop that keeps the tree prominent. Download the files into the same folder as your HTML file to try the relative URLs unchanged. Prepare the file, alternative text, and dimensions using the principles in Images: img, Alt Text, and Dimensions.

• 480-pixel-wide image
• 960-pixel-wide image
• 1600-pixel-wide image
• 800×800-pixel square crop

The first three preserve the scene and aspect ratio. The square file has a different composition for a narrow display.

Choose image resolution with srcset and sizes

The 480w, 960w, and 1600w descriptors in srcset give each file's actual pixel width. sizes describes the image's expected layout width under different viewport conditions.

<img class="example-fluid"
  src="html-image-sample-lake-tree-960-v1.webp"
  srcset="html-image-sample-lake-tree-480-v1.webp 480w,
          html-image-sample-lake-tree-960-v1.webp 960w,
          html-image-sample-lake-tree-1600-v1.webp 1600w"
  sizes="(max-width: 800px) 100vw, 800px"
  alt="A tree on a small island in a lake, with mountains beyond"
  width="1600" height="900">

This assumes the image is about as wide as the viewport up to 800 CSS pixels, and no wider than 800 CSS pixels above that. If your layout differs, change sizes to match it. src supplies a fallback for environments without srcset support.

.example-fluid {
  display: block;
  width: 100%;
  max-width: 800px;
  height: auto;
}

This CSS applies only to the first example, which has the example-fluid class. The browser can also consider device pixel density and zoom. A narrow viewport therefore does not guarantee that the 480-pixel file will be chosen. sizes describes displayed CSS pixels, not the width of the downloaded file.

Use density descriptors for a fixed display width

If an image is always displayed at 480 CSS pixels wide, you can offer 1x and 2x candidates. Do not use sizes with this form.

<img class="example-fixed"
  src="html-image-sample-lake-tree-480-v1.webp"
  srcset="html-image-sample-lake-tree-480-v1.webp 1x,
          html-image-sample-lake-tree-960-v1.webp 2x"
  alt="A tree on a small island in a lake, with mountains beyond"
  width="480" height="270">

.example-fixed {
  display: block;
  width: 480px;
  height: auto;
}

The first example's CSS does not apply to this image. This CSS fixes the displayed width at 480 pixels, so the image may overflow a narrower container. If the display width needs to change with the layout, use the earlier w and sizes approach. Do not mix w and x descriptors in one srcset.

Change the crop with picture

picture can offer a different composition instead of merely a different resolution. This example uses the square crop at viewport widths up to 600 pixels and a landscape image otherwise.

<picture class="example-picture">
  <source media="(max-width: 600px)"
          srcset="html-image-sample-lake-tree-square-800-v1.webp"
          width="800" height="800">
  <img src="html-image-sample-lake-tree-960-v1.webp"
       alt="A tree on a small island in a lake, with mountains beyond"
       width="960" height="540">
</picture>

Choosing a crop and fitting its display width are separate. Add this CSS in head's style element or the linked stylesheet so the picture image fits a narrow parent while preserving its ratio.

.example-picture img {
  display: block;
  max-width: 100%;
  height: auto;
}

The photo above shows the square-crop file used on narrow screens; this photo in the article does not itself switch with viewport width. picture still needs an img element with fallback content and alt. Each source supplies a condition and file candidate; the image's alternative text belongs on img.

Check which image the browser selected

Save all four image files, keeping their filenames, next to index.html. Put an HTML example inside body and its CSS in a style element in head or in a separate stylesheet. To test against the actual viewport width on mobile, add <meta name="viewport" content="width=device-width, initial-scale=1"> to head.

1. Open index.html in a browser and open the developer tools' Network panel.
2. Change the viewport width, disable the cache, and reload the page. Check the image request filenames to see which candidates loaded.
3. For the picture example, reload once at a viewport width of 600 pixels or less and once above 600 pixels. Check for the square crop at the narrower width and the landscape file at the wider width.

You can also check these values in the console. currentSrc shows the image URL currently selected by the browser. The first command targets the srcset example; the second targets the picture example.

document.querySelector('.example-fluid').currentSrc
document.querySelector('picture img').currentSrc

Even at the same viewport width, pixel density and zoom may change which srcset file is selected. If a larger file is already loaded, narrowing the window may not immediately replace it with a smaller one. Change the conditions, disable the cache, and reload before comparing.

Check resolution switching and art direction

The viewport is the browser area used to lay out the page. Device pixel density relates CSS pixels to physical display pixels. Density, zoom, and cache state can affect resolution selection even at the same viewport width, so do not promise one fixed srcset filename. Test the art-direction media condition separately from resolution switching.

If the wrong image is selected

• Check that each w descriptor matches the file's actual pixel width.
• Compare sizes with the CSS width at each viewport size.
• Use same-composition files for resolution switching and separate crops with picture.
• Keep a meaningful alt on the img inside picture.

For the detailed selection rules, see MDN's responsive images guide and the WHATWG HTML image specification.