srcset

Learn how to use the srcset attribute with width descriptors to serve optimized images based on device resolution and viewport size.

What it is

The srcset attribute allows you to provide multiple versions of an image file. When used with width descriptors (e.g., 300w, 600w), you tell the browser the intrinsic pixel width of each candidate image. The browser then calculates which image best fits the current layout and device pixel ratio, downloading only that specific file.

This mechanism relies on the concept of intrinsic width. Unlike height descriptors, width descriptors are generally preferred because they align more naturally with responsive design layouts where width is often the constrained dimension.

Why it matters

• Performance: Prevents mobile users from downloading large desktop-sized images, saving bandwidth and battery life.
• Quality: Ensures high-resolution displays (Retina/4K) receive sharp images without blurring.
• Simplicity: Requires no JavaScript; the browser handles selection natively.
• SEO: Faster page loads improve Core Web Vitals scores.

Syntax or steps

To use width descriptors, list your image sources separated by commas. Each source must end with a number followed by w, representing the image's actual pixel width.

<img src="fallback.jpg" 
     srcset="small.jpg 300w, medium.jpg 600w, large.jpg 1200w">

You should also include a sizes attribute if the image does not span the full viewport width, helping the browser make accurate calculations.

Example

Here is a realistic example serving three versions of a hero image. The sizes attribute tells the browser the image will take up 50% of the viewport on screens wider than 768px, and 100% otherwise.

<img src="hero-800.jpg" 
     alt="Mountain landscape"
     sizes="(max-width: 768px) 100vw, 50vw"
     srcset="hero-400.jpg 400w, 
             hero-800.jpg 800w, 
             hero-1600.jpg 1600w">

Part-by-part explanation:

• src="hero-800.jpg": A fallback for browsers that do not support srcset.
• sizes="(max-width: 768px) 100vw, 50vw": Defines the display width. On small screens, the image takes 100% of the viewport width (100vw). On larger screens, it takes 50%.
• srcset="...": Lists candidates. If a user has a standard screen (1x DPR) viewing a 768px wide window, the browser sees the image needs ~768px. It compares this against the candidates (400w, 800w, 1600w). It picks hero-800.jpg as the closest match that isn't too small.

Common mistakes

• Mixing descriptors: Do not mix w (width) and x (pixel density) descriptors in the same srcset. Choose one strategy per image tag.
• Incorrect widths: Ensure the number before w matches the actual pixel dimensions of the file. If image.jpg is 500px wide but labeled 1000w, the browser may select it when it shouldn't, causing blur.
• Missing sizes: Without sizes, the browser assumes the image is 100% of the viewport width. This can lead to poor choices for smaller column layouts.
• Forgetting the fallback: Always include a valid src attribute for older browsers or edge cases.

When to use it

Compare srcset with picture element usage below:

Use srcset when you simply need sharper images on high-DPI screens. Use <picture> when you need to swap entirely different images (e.g., a square crop for mobile vs. a wide banner for desktop).

Practice

Guided Exercise: Create an HTML snippet for an avatar image. You have files avatar-small.png (100px wide) and avatar-large.png (200px wide). Assume the avatar always displays at 100px CSS pixels.

Challenge: Write the code using srcset with width descriptors. Hint: Since the display size is fixed, you might consider pixel density descriptors instead, but try forcing width descriptors first.

Solution Hint: <img src="avatar-small.png" srcset="avatar-small.png 100w, avatar-large.png 200w" sizes="100px" alt="User Avatar">

Quick check

Question: What happens if you specify srcset="image.jpg 500w" but the actual file is only 300 pixels wide?

Answer: The browser believes the image is 500 pixels wide. It may select this image for a 400-pixel container, resulting in a blurry, upscaled image because the browser thinks it has enough resolution data.

Summary

The srcset attribute with width descriptors enables efficient, resolution-aware image loading. By accurately declaring intrinsic widths and using the sizes attribute, you ensure browsers download the optimal asset, balancing visual quality with performance.