Skip to main content

Page last updated 07 October 2026

A srcset offers the browser several renditions of the same image and lets it download only the one it needs. Every candidate must show the same picture, differing only in size. Where the image itself should change between breakpoints, use a picture element instead.

Width-based selection

Offer the same image at a range of widths, so a narrow or low-resolution device does not download a file far larger than it can display. Each candidate is labelled with the width it really is, and the sizes attribute tells the browser how wide the image will be displayed.

HTML
<img src="https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=800"
     srcset="https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=320 320w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=480 480w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=800 800w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=1024 1024w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=1600 1600w"
     sizes="100vw"
     width="1600" height="1067"
     alt="A lighthouse above a rocky shoreline at sunset">
  • The w descriptor is the actual width of that rendition in pixels, not a breakpoint. It must match the width the Image API was asked for.
  • src is the fallback for anything that does not understand srcset, so point it at a middling size rather than the smallest or the largest.
  • width and height give the browser the aspect ratio before the image arrives, so the page does not jump. Any candidate will do, as they all share the same shape.

When the image does not fill the viewport

Images in a responsive layout rarely occupy the whole width of the screen, and how much they occupy usually changes with the layout. The sizes attribute describes that, so the browser can pick the right candidate before it has laid the page out.

HTML
<img src="https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=800"
     srcset="https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=320 320w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=480 480w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=800 800w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=1024 1024w,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=1600 1600w"
     sizes="(max-width: 480px) 100vw,
            (max-width: 1024px) 50vw,
            800px"
     width="1600" height="1067"
     alt="A lighthouse above a rocky shoreline at sunset">

Read that as: below 480px the image spans the screen, up to 1024px it takes half the width, and above that it is a fixed 800 pixels. The conditions are tried in order and the first match wins, so the last entry carries no condition and acts as the default.

Device-pixel-ratio-based selection

Where an image is displayed at a fixed size, such as an avatar or a logo, describe the candidates by pixel density instead. A device with a high resolution display then takes a larger file and renders it at the same physical size, so it looks sharp rather than soft.

HTML
<img src="https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=300"
     srcset="https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=300 1x,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=450 1.5x,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=600 2x,
             https://www.contensis.com/image-library/resources-images/image-api-examples/coastal-landscape-with-rocky-shoreline.jpg?width=900 3x"
     width="300" height="200"
     alt="A lighthouse above a rocky shoreline at sunset">
  • Each candidate is the displayed width multiplied by its density, so a 300 pixel image needs a 600 pixel file at 2x.
  • Do not add a sizes attribute here. It applies only to width descriptors and is ignored alongside x ones.
  • Do not mix w and x descriptors in one srcset. Choose whichever suits the image and use it throughout.

To see which file a browser picks, open its developer tools, switch to the network panel and filter by images, then resize the window or change the device pixel ratio. Only the chosen rendition is downloaded.

Still need help?

If you still need help after reading this article, don't hesitate to reach out to the Contensis community on Slack or raise a support ticket to get help from our team.
New support request