HTML sizes Attribute

HTML sizes Attribute

The HTML sizes attribute provides sizing information that helps the browser select an appropriate image resource from a srcset containing width descriptors. It is used with responsive images on the <img> and <source> elements and has a different purpose when used with icon links.

Elements That Use the sizes Attribute

The sizes attribute is used with the <img>, <source>, and <link> elements. Its meaning depends on the element.

sizes and Responsive Images

For responsive images, the sizes attribute describes the intended layout width of the image. The browser combines this information with the width descriptors in srcset to choose an appropriate image resource.

<img src="image-400.jpg"
     srcset="image-400.jpg 400w,
             image-800.jpg 800w,
             image-1200.jpg 1200w"
     sizes="100vw"
     alt="Example image">

In this example, sizes="100vw" tells the browser that the image is intended to occupy the full width of the viewport. The browser can use that information, along with factors such as display density, to choose a suitable candidate from srcset.

Source Size List

The sizes value for responsive images can contain a comma-separated list of media conditions and source sizes. The browser evaluates the entries from left to right and uses the first media condition that matches. The final entry normally provides the size to use when none of the earlier conditions match.

sizes="(max-width: 600px) 100vw,
       (max-width: 1000px) 50vw,
       33vw"

In this example, the intended image width is the full viewport width at up to 600 pixels, half of the viewport width at up to 1000 pixels, and one-third of the viewport width for wider viewports.

Percentages are not allowed as source-size values. Viewport units such as vw, absolute lengths such as px, and supported CSS math functions such as calc() can be used.

Using sizes with srcset

The sizes attribute is designed to work with srcset image candidates that use width descriptors such as 400w, 800w, and 1200w.

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

The w descriptor identifies each image's intrinsic width. The sizes attribute describes the intended layout width. The browser uses both pieces of information to determine which image candidate is appropriate.

When a sizes attribute is present for responsive image selection, the image candidates in the associated srcset use width descriptors rather than pixel-density descriptors such as 1x or 2x.

Using sizes with <source>

The <source> elements inside a <picture> element can also use sizes when their srcset contains width descriptors.

<picture>
  <source media="(max-width: 600px)"
          srcset="small-400.jpg 400w,
                  small-800.jpg 800w"
          sizes="100vw">
  <img src="large-800.jpg"
       srcset="large-800.jpg 800w,
               large-1200.jpg 1200w"
       sizes="50vw"
       alt="Example image">
</picture>

When a <source> element is selected, its sizes value contributes the source size used to choose a candidate from that source's srcset.

The auto Value

The auto keyword can be used for responsive images when automatic sizing is allowed. A common case is a lazily loaded <img> element whose rendered width can be used as the source size.

<img src="image-400.jpg"
     srcset="image-400.jpg 400w,
             image-800.jpg 800w,
             image-1200.jpg 1200w"
     sizes="auto"
     loading="lazy"
     width="400"
     height="250"
     alt="Example image">

When used, auto must be the first entry in the source size list. Fallback sizes can follow it, such as sizes="auto, 100vw", for user agents that cannot use automatic sizing.

Using sizes with <link>

The sizes attribute has a different meaning on a <link> element. For links representing icons, it provides advisory information about the sizes of the referenced icon resource.

<link rel="icon"
      href="/favicon-32.png"
      sizes="32x32"
      type="image/png">

Multiple icon sizes can be supplied as space-separated values, and the keyword any can be used when the icon can be scaled to any size, such as an appropriate vector icon.

<link rel="icon"
      href="/favicon.svg"
      sizes="any"
      type="image/svg+xml">

Do not confuse the sizes attribute used for icon links with the imagesizes attribute used with responsive image preloading. They are separate attributes with different purposes.

Common Mistakes

Do not use sizes as a replacement for CSS width. For responsive images, it tells the browser the intended layout width for resource selection; CSS still controls the image's actual rendered layout.

Do not use percentages such as 50% as responsive image source-size values. Use an appropriate length such as 50vw when the intended size is relative to the viewport.

Do not mix width descriptors such as 800w with pixel-density descriptors such as 2x in the same srcset.

Make sure the width descriptor for each image candidate matches that image file's natural width. Incorrect descriptors can cause the browser to make an inappropriate resource selection.

Do not confuse sizes on <link rel="icon"> with responsive image sizing. On icon links, the attribute describes the dimensions of available icon resources.

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 sizes attribute is widely supported on the elements where it applies. Support for newer values and behaviors can have a different compatibility history from the basic attribute.

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

The example uses srcset with width descriptors and a sizes attribute to help the browser select an appropriate image for the available display width. Drag the divider between the code and result panes to change the preview width and see which image is displayed.

Summary

The HTML sizes attribute provides sizing information used for resource selection. On <img> and <source>, it works with srcset width descriptors to describe the intended layout width of a responsive image so the browser can choose an appropriate resource. On icon <link> elements, it describes the available icon dimensions. The attribute does not replace CSS sizing and should accurately reflect the layout in which the resource will be displayed.