responsive-images

# Responsive Images

**Status**: Production Ready ✅
**Last Updated**: 2026-01-14
**Standards**: Web Performance Best Practices, Core Web Vitals

---

## Quick Start

### Basic Responsive Image

<img
  src="/images/hero-800.jpg"
  srcset="
    /images/hero-400.jpg 400w,
    /images/hero-800.jpg 800w,
    /images/hero-1200.jpg 1200w,
    /images/hero-1600.jpg 1600w
  "
  sizes="(max-width: 640px) 100vw,
         (max-width: 1024px) 90vw,
         1200px"
  alt="Hero image description"
  width="1200"
  height="675"
  loading="lazy"
/>

### Hero Image (LCP)

<img
  src="/images/hero-1200.jpg"
  srcset="
    /images/hero-800.jpg 800w,
    /images/hero-1200.jpg 1200w,
    /images/hero-1600.jpg 1600w
  "
  sizes="100vw"
  alt="Hero image"
  width="1600"
  height="900"
  loading="eager"
  fetchpriority="high"
/>

---

## Configuration

### Recommended Image Sizes

| Use Case | Widths to Generate | Sizes Attribute |
|----------|-------------------|-----------------|
| Full-width hero | 800w, 1200w, 1600w, 2400w | 100vw |
| Content width | 400w, 800w, 1200w | (max-width: 768px) 100vw, 800px |
| Grid cards (3-col) | 300w, 600w, 900w | (max-width: 768px) 100vw, 33vw |
| Sidebar thumbnail | 150w, 300w | 150px |

### Lazy Loading Rules

| Image Position | loading | fetchpriority | Why |
|----------------|---------|---------------|-----|
| Hero/LCP | eager | high | Optimize LCP, prioritize download |
| Above fold (not LCP) | eager | omit | Load normally |
| Below fold | lazy | omit | Defer until near viewport |
| Off-screen carousel | lazy | omit | Defer until interaction |

---

## Common Patterns

### Full-Width Responsive Image

<img
  src="/images/banner-1200.jpg"
  srcset="
    /images/banner-600.jpg 600w,
    /images/banner-1200.jpg 1200w,
    /images/banner-1800.jpg 1800w,
    /images/banner-2400.jpg 2400w
  "
  sizes="100vw"
  alt="Full width banner"
  width="2400"
  height="800"
  loading="lazy"
  class="w-full h-auto"
/>

### Grid Card Image (3 columns)

<img
  src="/images/card-600.jpg"
  srcset="
    /images/card-300.jpg 300w,
    /images/card-600.jpg 600w,
    /images/card-900.jpg 900w
  "
  sizes="(max-width: 768px) 100vw,
         (max-width: 1024px) 50vw,
         33vw"
  alt="Card image"
  width="900"
  height="600"
  loading="lazy"
  class="w-full h-auto"
/>

### Fixed Aspect Ratio Container

<div class="aspect-[16/9] overflow-hidden">
  <img
    src="/images/video-thumbnail-800.jpg"
    srcset="
      /images/video-thumbnail-400.jpg 400w,
      /images/video-thumbnail-800.jpg 800w,
      /images/video-thumbnail-1200.jpg 1200w
    "
    sizes="(max-width: 768px) 100vw, 800px"
    alt="Video thumbnail"
    width="800"
    height="450"
    loading="lazy"
    class="w-full h-full object-cover"
  />
</div>

### Modern Formats (WebP + AVIF)

<picture>
  <source
    srcset="
      /images/hero-800.avif 800w,
      /images/hero-1200.avif 1200w,
      /images/hero-1600.avif 1600w
    "
    sizes="100vw"
    type="image/avif"
  />
  <source
    srcset="
      /images/hero-800.webp 800w,
      /images/hero-1200.webp 1200w,
      /images/hero-1600.webp 1600w
    "
    sizes="100vw"
    type="image/webp"
  />
  <img
    src="/images/hero-1200.jpg"
    srcset="
      /images/hero-800.jpg 800w,
      /images/hero-1200.jpg 1200w,
      /images/hero-1600.jpg 1600w
    "
    sizes="100vw"
    alt="Hero image"
    width="1600"
    height="900"
    loading="eager"
    fetchpriority="high"
  />
</picture>

### Art Direction (Different Crops)

<picture>
  <source
    media="(max-width: 640px)"
    srcset="
      /images/product-portrait-400.jpg 400w,
      /images/product-portrait-800.jpg 800w
    "
    sizes="100vw"
  />
  <source
    media="(min-width: 641px)"
    srcset="
      /images/product-landscape-800.jpg 800w,
      /images/product-landscape-1200.jpg 1200w,
      /images/product-landscape-1600.jpg 1600w
    "
    sizes="(max-width: 1024px) 90vw, 1200px"
  />
  <img
    src="/images/product-landscape-1200.jpg"
    alt="Product image"
    width="1200"
    height="675"
    loading="lazy"
  />
</picture>

---

## Error Prevention

### Always Include Width and Height

**Problem**: Layout shift when images load (poor CLS score)

<!-- ❌ WRONG - causes layout shift -->
<img src="/image.jpg" alt="Image" loading="lazy" />

<!-- ✅ CORRECT - browser reserves space -->
<img
  src="/image.jpg"
  alt="Image"
  width="800"
  height="600"
  loading="lazy"
/>

**Source**: [Web.dev - Optimize CLS](https://web.dev/articles/optimize-cls)

### Don't Lazy Load LCP Images

**Problem**: Delayed LCP, poor Core Web Vitals score

<!-- ❌ WRONG - delays LCP -->
<img
  src="/hero.jpg"
  alt="Hero"
  loading="lazy"
/>

<!-- ✅ CORRECT - prioritizes LCP -->
<img
  src="/hero.jpg"
  alt="Hero"
  loading="eager"
  fetchpriority="high"
/>

**Source**: [Web.dev - Optimize LCP](https://web.dev/articles/optimize-lcp)

### Use Width Descriptors (w), Not Density (x)

**Problem**: Browser can't choose optimal image for viewport

<!-- ❌ WRONG - only considers DPR -->
<img
  src="/image.jpg"
  srcset="/image.jpg 1x, /[email protected] 2x"
  alt="Image"
/>

<!-- ✅ CORRECT - considers viewport + DPR -->
<img
  src="/image-800.jpg"
  srcset="
    /image-400.jpg 400w,
    /image-800.jpg 800w,
    /image-1200.jpg 1200w
  "
  sizes="(max-width: 768px) 100vw, 800px"
  alt="Image"
  width="800"
  height="600"
/>

**Exception**: Density descriptors are appropriate for fixed-size images like logos.

### Always Include Alt Text

**Problem**: Fails accessibility, SEO, and screen readers

<!-- ❌ WRONG -->
<img src="/product.jpg" />

<!-- ✅ CORRECT - descriptive alt text -->
<img src="/product.jpg" alt="Red leather messenger bag with brass buckles" />

<!-- ✅ CORRECT - decorative images use empty alt -->
<img src="/decorative-line.svg" alt="" role="presentation" />

### Aspect Ratio with object-fit

**Problem**: Image stretches or squashes when container size differs from image dimensions

<!-- ❌ WRONG - image distorts -->
<div class="w-full h-64">
  <img src="/image.jpg" alt="Image" class="w-full h-full" />
</div>

<!-- ✅ CORRECT - maintains aspect ratio -->
<div class="w-full h-64">
  <img
    src="/image.jpg"
    alt="Image"
    class="w-full h-full object-cover"
  />
</div>

---

## Quick Reference

### Sizes Attribute Patterns

<!-- Full width -->
sizes="100vw"

<!-- Content width (max 800px) -->
sizes="(max-width: 768px) 100vw, 800px"

<!-- Sidebar (fixed 300px) -->
sizes="300px"

<!-- 2-column grid -->
sizes="(max-width: 768px) 100vw, 50vw"

<!-- 3-column grid -->
sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"

<!-- Responsive with max-width -->
sizes="(max-width: 640px) 100vw, (max-width: 1024px) 90vw, 1200px"

### Common Aspect Ratios

| Ratio | CSS | Use Case |
|-------|-----|----------|
| 16:9 | aspect-[16/9] | Video thumbnails, hero images |
| 4:3 | aspect-[4/3] | Standard photos |
| 3:2 | aspect-[3/2] | DSLR photos |
| 1:1 | aspect-square | Profile pictures, Instagram-style |
| 21:9 | aspect-[21/9] | Ultrawide banners |

### object-fit Values

| Value | Behavior | Use Case |
|-------|----------|----------|
| cover | Fill container, crop edges | Card images, backgrounds |
| contain | Fit inside, preserve all content | Logos, product photos |
| fill | Stretch to fill | Avoid unless necessary |
| scale-down | Smaller of contain or original size | Mixed content sizes |

### Format Comparison

| Format | Quality | File Size | Browser Support | Use Case |
|--------|---------|-----------|-----------------|----------|
| JPEG | Good | Medium | 100% | Photos, complex images |
| PNG | Lossless | Large | 100% | Logos, transparency |
| WebP | Excellent | Small | 97%+ | Modern browsers, photos |
| AVIF | Excellent | Smallest | 90%+ | Cutting-edge, fallback required |

**Recommended Strategy**: AVIF → WebP → JPEG fallback using <picture>

---

## Resources

- [Web.dev: Responsive Images](https://web.dev/articles/responsive-images)
- [MDN: Responsive Images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)
- [Web.dev: Serve Images in Modern Formats](https://web.dev/articles/serve-images-webp)
- [Web.dev: Optimize Cumulative Layout Shift](https://web.dev/articles/optimize-cls)
- [Cloudflare Images Documentation](https://developers.cloudflare.com/images/)

---

**Token Efficiency**: ~70% savings by preventing trial-and-error with srcset/sizes syntax
**Errors Prevented**: 6 common responsive image issues documented above


---

# Responsive Images Corrections

## Always Use srcset for Images >400px

**Problem**: Single-size images waste bandwidth on mobile and look pixelated on retina displays.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| <img src="/image.jpg"> | <img srcset="... 400w, ... 800w, ... 1200w" sizes="..."> |

<!-- ❌ WRONG - wastes bandwidth, no retina support -->
<img src="/image-1200.jpg" alt="Image" />

<!-- ✅ CORRECT - responsive sizes -->
<img
  src="/image-800.jpg"
  srcset="
    /image-400.jpg 400w,
    /image-800.jpg 800w,
    /image-1200.jpg 1200w
  "
  sizes="(max-width: 768px) 100vw, 800px"
  alt="Image"
  width="800"
  height="600"
  loading="lazy"
/>

**Exception**: Small fixed-size images like logos (<200px) can use density descriptors or single size.

## Always Use Lazy Loading for Below-Fold Images

**Problem**: Loading all images immediately delays page load and LCP.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| <img src="..."> (no loading attr) | <img src="..." loading="lazy"> |
| loading="lazy" on hero image | loading="eager" fetchpriority="high" |

<!-- ❌ WRONG - loads all images immediately -->
<img src="/content-image.jpg" alt="Content" />

<!-- ✅ CORRECT - defers below-fold images -->
<img src="/content-image.jpg" alt="Content" loading="lazy" />

<!-- ✅ CORRECT - prioritizes LCP image -->
<img
  src="/hero.jpg"
  alt="Hero"
  loading="eager"
  fetchpriority="high"
/>

## Always Include Alt Text

**Problem**: Fails accessibility, SEO, and screen reader support.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| <img src="..."> | <img src="..." alt="Descriptive text"> |
| alt="image" | Descriptive alt text |
| Missing alt on decorative images | alt="" role="presentation" |

<!-- ❌ WRONG -->
<img src="/product.jpg" />
<img src="/product.jpg" alt="image" />

<!-- ✅ CORRECT - descriptive alt -->
<img src="/product.jpg" alt="Red leather messenger bag with brass buckles" />

<!-- ✅ CORRECT - decorative images -->
<img src="/decorative-line.svg" alt="" role="presentation" />

## Always Prevent Layout Shift (Aspect Ratio or Dimensions)

**Problem**: Images loading without reserved space cause layout shift, hurting CLS score.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| <img src="..."> (no dimensions) | <img src="..." width="..." height="..."> |
| Container without aspect-ratio | <div class="aspect-[16/9]"> |

<!-- ❌ WRONG - causes layout shift -->
<img src="/image.jpg" alt="Image" loading="lazy" />

<!-- ✅ CORRECT - explicit dimensions -->
<img
  src="/image.jpg"
  alt="Image"
  width="800"
  height="600"
  loading="lazy"
/>

<!-- ✅ CORRECT - aspect-ratio container -->
<div class="aspect-[16/9]">
  <img
    src="/image.jpg"
    alt="Image"
    width="800"
    height="450"
    loading="lazy"
    class="w-full h-full object-cover"
  />
</div>

## Never Use loading="lazy" on LCP Images

**Problem**: Delays Largest Contentful Paint, hurting Core Web Vitals score.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| loading="lazy" on hero/first image | loading="eager" fetchpriority="high" |

<!-- ❌ WRONG - delays LCP -->
<img
  src="/hero.jpg"
  alt="Hero"
  loading="lazy"
/>

<!-- ✅ CORRECT - prioritizes LCP -->
<img
  src="/hero.jpg"
  alt="Hero"
  loading="eager"
  fetchpriority="high"
/>

**Rule of Thumb**: First 2-3 images visible on page load should be loading="eager".

## Use fetchpriority="high" for Hero Images

**Problem**: LCP image competes with other resources, delaying load.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| Hero image without fetchpriority | fetchpriority="high" |

<!-- ❌ WRONG - no priority boost -->
<img
  src="/hero.jpg"
  alt="Hero"
  loading="eager"
/>

<!-- ✅ CORRECT - prioritizes download -->
<img
  src="/hero.jpg"
  alt="Hero"
  loading="eager"
  fetchpriority="high"
/>

## Use Width Descriptors (w), Not Density (x) for Responsive Images

**Problem**: Browser can't optimize for viewport size.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| srcset="... 1x, ... 2x" for content images | srcset="... 400w, ... 800w" sizes="..." |

<!-- ❌ WRONG - only considers DPR, not viewport -->
<img
  src="/image.jpg"
  srcset="/image.jpg 1x, /[email protected] 2x"
  alt="Image"
/>

<!-- ✅ CORRECT - considers viewport + DPR -->
<img
  src="/image-800.jpg"
  srcset="
    /image-400.jpg 400w,
    /image-800.jpg 800w,
    /image-1200.jpg 1200w
  "
  sizes="(max-width: 768px) 100vw, 800px"
  alt="Image"
  width="800"
  height="600"
/>

**Exception**: Density descriptors are appropriate for fixed-size images like logos.

<!-- ✅ CORRECT - fixed logo size -->
<img
  src="/logo.png"
  srcset="/logo.png 1x, /[email protected] 2x"
  alt="Logo"
  width="150"
  height="50"
/>

## Always Include sizes Attribute with Width Descriptors

**Problem**: Browser defaults to 100vw, choosing unnecessarily large images.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| srcset="... 400w, ... 800w" (no sizes) | Add sizes="..." |

<!-- ❌ WRONG - browser assumes 100vw -->
<img
  src="/image-800.jpg"
  srcset="/image-400.jpg 400w, /image-800.jpg 800w"
  alt="Image"
/>

<!-- ✅ CORRECT - specifies display size -->
<img
  src="/image-800.jpg"
  srcset="/image-400.jpg 400w, /image-800.jpg 800w"
  sizes="(max-width: 768px) 100vw, 800px"
  alt="Image"
  width="800"
  height="600"
/>

## Use Modern Formats (AVIF, WebP) with Fallbacks

**Problem**: Serving only JPEG/PNG wastes 50-70% potential bandwidth savings.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| <img src="/image.jpg"> | <picture> with AVIF → WebP → JPEG |

<!-- ❌ WRONG - missing modern formats -->
<img src="/image.jpg" alt="Image" />

<!-- ✅ CORRECT - AVIF → WebP → JPEG fallback -->
<picture>
  <source
    srcset="
      /image-400.avif 400w,
      /image-800.avif 800w,
      /image-1200.avif 1200w
    "
    sizes="(max-width: 768px) 100vw, 800px"
    type="image/avif"
  />
  <source
    srcset="
      /image-400.webp 400w,
      /image-800.webp 800w,
      /image-1200.webp 1200w
    "
    sizes="(max-width: 768px) 100vw, 800px"
    type="image/webp"
  />
  <img
    src="/image-800.jpg"
    srcset="
      /image-400.jpg 400w,
      /image-800.jpg 800w,
      /image-1200.jpg 1200w
    "
    sizes="(max-width: 768px) 100vw, 800px"
    alt="Image"
    width="800"
    height="600"
    loading="lazy"
  />
</picture>

## Use object-fit: cover for Fixed Aspect Ratio Containers

**Problem**: Image stretches or squashes when container size differs from image dimensions.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| No object-fit with aspect-ratio | object-cover or object-contain |

<!-- ❌ WRONG - image distorts -->
<div class="w-full h-64">
  <img src="/image.jpg" alt="Image" class="w-full h-full" />
</div>

<!-- ✅ CORRECT - maintains aspect ratio, crops edges -->
<div class="w-full h-64">
  <img
    src="/image.jpg"
    alt="Image"
    class="w-full h-full object-cover"
  />
</div>

<!-- ✅ CORRECT - maintains aspect ratio, shows all content -->
<div class="w-full h-64">
  <img
    src="/logo.svg"
    alt="Logo"
    class="w-full h-full object-contain"
  />
</div>

## Use Correct Source Order in picture Element

**Problem**: Browser picks first matching source, wrong order serves suboptimal format.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| JPEG before WebP | AVIF → WebP → JPEG |
| Missing type attribute | Always include type="image/..." |

<!-- ❌ WRONG - JPEG before WebP -->
<picture>
  <source srcset="/image.jpg" type="image/jpeg" />
  <source srcset="/image.webp" type="image/webp" />
  <img src="/image.jpg" alt="Image" />
</picture>

<!-- ✅ CORRECT - best to worst -->
<picture>
  <source srcset="/image.avif" type="image/avif" />
  <source srcset="/image.webp" type="image/webp" />
  <img src="/image.jpg" alt="Image" width="800" height="600" />
</picture>

## Use Art Direction (picture) for Different Crops

**Problem**: Same crop doesn't work well at all viewport sizes.

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| Same image at all sizes | Different crops via <picture> |
| CSS-only cropping | Server-side cropped images |

<!-- ❌ WRONG - portrait crop stretched wide on desktop -->
<img
  src="/portrait.jpg"
  srcset="/portrait-400.jpg 400w, /portrait-800.jpg 800w"
  sizes="100vw"
  alt="Image"
/>

<!-- ✅ CORRECT - portrait on mobile, landscape on desktop -->
<picture>
  <source
    media="(max-width: 640px)"
    srcset="/image-portrait-400.jpg 400w, /image-portrait-800.jpg 800w"
    sizes="100vw"
  />
  <img
    src="/image-landscape-1200.jpg"
    srcset="/image-landscape-800.jpg 800w, /image-landscape-1200.jpg 1200w"
    sizes="(max-width: 1024px) 90vw, 1200px"
    alt="Image"
    width="1200"
    height="675"
    loading="lazy"
  />
</picture>

## Applies To

- **/*.html
- **/*.tsx, **/*.jsx (React components)
- **/*.vue, **/*.svelte (other frameworks)
- Any file with <img> or <picture> elements

## Testing Commands

# Check for missing width/height
grep -r '<img' --include="*.html" --include="*.tsx" | grep -v 'width=' | grep -v 'height='

# Check for missing alt
grep -r '<img' --include="*.html" --include="*.tsx" | grep -v 'alt='

# Check for missing loading attribute
grep -r '<img' --include="*.html" --include="*.tsx" | grep -v 'loading='

# Run Lighthouse audit
npx lighthouse https://example.com --only-categories=performance --view

## Quick Wins

1. **Add width/height to all images** - Prevents CLS
2. **Add loading="lazy" to below-fold images** - Reduces initial load
3. **Add fetchpriority="high" to hero image** - Improves LCP
4. **Generate WebP versions** - 40-50% size savings
5. **Add srcset for images >400px** - Optimize for mobile

## References

- [Web.dev: Optimize Images](https://web.dev/articles/optimize-images)
- [Web.dev: Responsive Images](https://web.dev/articles/responsive-images)
- [Web.dev: Lazy Loading](https://web.dev/articles/browser-level-image-lazy-loading)
- [Web.dev: Optimize CLS](https://web.dev/articles/optimize-cls)
- [Web.dev: Optimize LCP](https://web.dev/articles/optimize-lcp)