HTML imagesizes Attribute

HTML imagesizes Attribute

The HTML imagesizes attribute specifies responsive image sizing information for an image being preloaded with a <link> element. It works with imagesrcset so the browser can choose an appropriate image resource before the corresponding <img> element is encountered.

Syntax

The imagesizes attribute is used on a <link> element that preloads a responsive image. It is normally paired with imagesrcset.

<link rel="preload"
  as="image"
  imagesrcset="/img/images/image-300x200.png 300w,
               /img/images/image-600x400.png 600w,
               /img/images/image-900x600.png 900w,
               /img/images/image-1200x800.png 1200w"
  imagesizes="(max-width: 600px) 100vw, 900px">

The browser uses the image candidates in imagesrcset together with the sizing information in imagesizes when deciding which resource to preload.

Attribute Value

The imagesizes attribute accepts a source-size list using the same general syntax as the sizes attribute on responsive images.

imagesizes="100vw"

imagesizes="(max-width: 600px) 100vw, 900px"

imagesizes="(max-width: 800px) 50vw, 600px"

The browser evaluates the source-size information when selecting a resource from the candidates supplied by imagesrcset.

Elements That Use the imagesizes Attribute

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

The similarly named sizes attribute is used on responsive <img> and <source> elements. The <link> element uses imagesizes instead.

Using the imagesizes Attribute

Responsive image preloading can allow the browser to begin fetching an appropriate image before it reaches the <img> element in the document body.

<link rel="preload"
  as="image"
  imagesrcset="/img/images/image-300x200.png 300w,
               /img/images/image-600x400.png 600w,
               /img/images/image-900x600.png 900w,
               /img/images/image-1200x800.png 1200w"
  imagesizes="(max-width: 600px) 100vw, 900px">

In this example, imagesizes tells the browser that the image is expected to occupy the full viewport width when the viewport is 600 pixels wide or less. Otherwise, its expected display size is 900 pixels.

The browser can combine that information with the available image candidates and the device's display characteristics when choosing which resource to preload.

Using imagesizes with imagesrcset

The imagesizes attribute is designed to work with imagesrcset. The imagesrcset attribute provides the available image candidates, while imagesizes describes the expected display size.

<link rel="preload"
  as="image"
  imagesrcset="/img/images/image-300x200.png 300w,
               /img/images/image-600x400.png 600w,
               /img/images/image-900x600.png 900w,
               /img/images/image-1200x800.png 1200w"
  imagesizes="(max-width: 600px) 100vw, 900px">

When width descriptors such as 300w, 600w, 900w, and 1200w are used in imagesrcset, accurate sizing information helps the browser make an appropriate resource selection.

imagesizes vs. sizes

The imagesizes and sizes attributes serve closely related purposes but are used on different elements.

<head>
  <link rel="preload"
    as="image"
    imagesrcset="/img/images/image-300x200.png 300w,
                 /img/images/image-600x400.png 600w,
                 /img/images/image-900x600.png 900w,
                 /img/images/image-1200x800.png 1200w"
    imagesizes="(max-width: 600px) 100vw, 900px">
</head>

<body>
  <img src="/img/images/image-900x600.png"
    srcset="/img/images/image-300x200.png 300w,
            /img/images/image-600x400.png 600w,
            /img/images/image-900x600.png 900w,
            /img/images/image-1200x800.png 1200w"
    sizes="(max-width: 600px) 100vw, 900px"
    alt="Responsive image example">
</body>

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

Common Mistakes

Do not use imagesizes on an <img> element. Use the sizes attribute there instead.

<!-- Incorrect -->
<img src="/img/images/image-900x600.png"
  srcset="/img/images/image-300x200.png 300w,
          /img/images/image-600x400.png 600w,
          /img/images/image-900x600.png 900w,
          /img/images/image-1200x800.png 1200w"
  imagesizes="100vw"
  alt="Responsive image example">

<!-- Correct -->
<img src="/img/images/image-900x600.png"
  srcset="/img/images/image-300x200.png 300w,
          /img/images/image-600x400.png 600w,
          /img/images/image-900x600.png 900w,
          /img/images/image-1200x800.png 1200w"
  sizes="100vw"
  alt="Responsive image example">

Do not confuse imagesizes with the sizes attribute used for other purposes on <link>, such as specifying icon sizes.

When preloading responsive images, make sure the preload information corresponds to the image that will actually be used by the page. Mismatched values can cause the browser to preload one resource and later request another.

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 imagesizes 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 imagesizes Attribute

The example shows how imagesizes is paired with imagesrcset when preloading a responsive image. Change the source-size value in the editor to see how the preload markup corresponds to the responsive image.

Summary

The HTML imagesizes attribute provides responsive image sizing information on a <link> element used to preload an image. It works with imagesrcset to help the browser select an appropriate image candidate before the corresponding image is encountered in the document. The related sizes attribute is used on <img> and <source> elements.