HTML imagesrcset Attribute

HTML imagesrcset Attribute

The HTML imagesrcset attribute provides one or more responsive image candidates for an image being preloaded with a <link> element. It can work with imagesizes so the browser can select an appropriate image resource before the corresponding <img> element is encountered.

Syntax

The imagesrcset attribute is used on a <link> element with rel="preload" and as="image". Its value contains one or more image candidates separated by commas.

<link rel="preload"
  as="image"
  imagesrcset="small.jpg 400w, medium.jpg 800w, large.jpg 1200w"
  imagesizes="(max-width: 600px) 100vw, 800px">

The browser evaluates the candidates and can preload the image that best matches the current conditions.

Attribute Value

The imagesrcset attribute accepts a comma-separated list of image candidate strings. Each candidate contains an image URL and can include a width or pixel-density descriptor.

imagesrcset="small.jpg 400w, large.jpg 800w"

imagesrcset="image.jpg 1x, image-2x.jpg 2x"

The browser selects from the candidates rather than downloading every image listed in imagesrcset.

Elements That Use the imagesrcset Attribute

The imagesrcset attribute is used with the <link> element.

The similarly named srcset attribute is used on <img> and <source> elements. Responsive image preloading with <link> uses imagesrcset instead.

Using the imagesrcset Attribute

Responsive image preloading allows the browser to begin fetching an appropriate image before it encounters the image in the document body.

<link rel="preload"
  as="image"
  imagesrcset="/img/photo-400.jpg 400w,
               /img/photo-800.jpg 800w,
               /img/photo-1200.jpg 1200w"
  imagesizes="(max-width: 600px) 100vw, 800px">

In this example, the browser can select from three image candidates. The imagesizes attribute supplies additional information about the expected display size so the browser can make an appropriate selection.

The imagesrcset attribute is relevant to <link> elements when rel is set to preload and as is set to image.

Image Candidate Descriptors

Image candidates can use width descriptors or pixel-density descriptors to describe the resources available to the browser.

Width descriptors are commonly used with imagesizes so the browser can compare the expected display size with the intrinsic widths of the available images.

imagesrcset="photo-400.jpg 400w,
             photo-800.jpg 800w,
             photo-1200.jpg 1200w"

Pixel-density descriptors can be useful when the image is expected to display at a fixed CSS size.

imagesrcset="logo.png 1x, logo-2x.png 2x"

Using imagesrcset with imagesizes

When imagesrcset uses width descriptors, imagesizes provides the source-size information needed for responsive resource selection.

<link rel="preload"
  as="image"
  imagesrcset="/img/image-400.jpg 400w,
               /img/image-800.jpg 800w"
  imagesizes="(max-width: 600px) 100vw, 800px">

If width descriptors are used but the required sizing information is unavailable, the browser cannot use those candidates as intended for responsive image preloading.

imagesrcset vs. srcset

The imagesrcset and srcset attributes use closely related image-candidate syntax but apply to different elements.

<head>
  <link rel="preload"
    as="image"
    imagesrcset="/img/photo-400.jpg 400w, /img/photo-800.jpg 800w"
    imagesizes="(max-width: 600px) 100vw, 800px">
</head>

<body>
  <img src="/img/photo-800.jpg"
    srcset="/img/photo-400.jpg 400w, /img/photo-800.jpg 800w"
    sizes="(max-width: 600px) 100vw, 800px"
    alt="Example">
</body>

When a preload corresponds to an image used later in the page, the preload's imagesrcset and imagesizes values should describe the same responsive image selection as the image's srcset and sizes values.

Common Mistakes

Do not use imagesrcset on an <img> element. Use srcset instead.

<!-- Incorrect -->
<img src="photo.jpg"
  imagesrcset="photo-400.jpg 400w, photo-800.jpg 800w"
  alt="Example">

<!-- Correct -->
<img src="photo.jpg"
  srcset="photo-400.jpg 400w, photo-800.jpg 800w"
  sizes="100vw"
  alt="Example">

Do not use imagesrcset for an ordinary <link> resource. It is intended for image preloads using rel="preload" with as="image".

When width descriptors are used, include matching imagesizes information. Also make sure the preload candidates correspond to the responsive image used later in the document so the browser does not preload an unnecessary resource.

Browser Support

Baseline: Widely available indicates a feature has been supported by core browsers for at least 30 months. At this stage, the feature is considered stable and safe for most websites to use without needing to worry about compatibility issues or fallbacks, as it is supported by the vast majority of users' devices and browser versions.

The imagesrcset attribute on the <link> element is widely supported in current core browsers.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the imagesrcset Attribute

The example shows how imagesrcset supplies responsive image candidates for a preload. Change the candidate list or descriptors in the editor to experiment with the markup.

Summary

The HTML imagesrcset attribute provides responsive image candidates on a <link> element used to preload an image. Candidates can use width or pixel-density descriptors, and imagesizes supplies sizing information when width descriptors are used. The related srcset attribute is used on <img> and <source> elements.