Image Processors

Images are the largest contributors to page weight and Cumulative Layout Shift (CLS) on most sites. pageflare applies image-specific optimizations that target both performance metrics and visual stability.

Dimension detection

The dimension detection processor reads each image file and extracts its intrinsic width and height, then propagates that information to the HTML processor. Any <img> element that references the image but is missing width or height attributes gets them added.

Why this matters for CLS

When a browser encounters an <img> tag without declared dimensions, it cannot reserve space for the image before it downloads. As the image loads, the browser reflows the page around it, pushing other content down — this is layout shift. The Cumulative Layout Shift Core Web Vital measures this and a poor CLS score directly affects Google Search ranking.

Adding explicit width and height attributes lets the browser compute the aspect ratio from CSS height: auto and reserve the correct amount of space before the image arrives:

<!-- Before: no reserved space, causes layout shift -->
<img src="/photos/hero.jpg" alt="Hero">

<!-- After: browser reserves correct space immediately -->
<img src="/photos/hero.jpg" alt="Hero" width="1200" height="630">

Supported formats

Dimension detection supports:

• JPEG
• PNG
• WebP
• GIF
• AVIF
• SVG (via viewBox attribute or width/height attributes)

The processor reads only the minimal header data needed to find the dimension information, keeping memory usage low even when processing thousands of images.

Note

If an <img> tag already has both width and height attributes, those values are preserved. pageflare does not override explicit markup.

Non-numeric values

Width and height attributes set to non-numeric strings (e.g. width="auto" or height="100%") are treated as missing. pageflare replaces them with the intrinsic pixel dimensions from the image file.

Adaptive sizing (srcset) PRO

Most images on a site are served at the same resolution regardless of whether the visitor is on a 320px mobile screen or a 4K desktop display. The adaptive sizing processor generates multiple resized variants of each image and injects a srcset attribute so the browser can pick the most appropriate version.

How it works

1. Variant generation — for each source image, pageflare generates scaled-down variants at a set of configured breakpoints (default: 320, 640, 960, 1280, 1920 px wide). Variants are only generated at sizes smaller than the original — no upscaling.

2. Format selection — if the source is a JPEG or PNG, pageflare generates both WebP and the original format variants. WebP is listed first in srcset so modern browsers prefer it. A <picture> element is used when format fallback is needed.

3. srcset injection — the HTML processor reads the variant map produced here and rewrites matching <img> elements to include srcset and sizes attributes.

<!-- Before -->
<img src="/photos/team.jpg" alt="Team photo" width="1200" height="800">

<!-- After -->
<picture>
  <source
    srcset="/photos/team-320w.webp 320w, /photos/team-640w.webp 640w, /photos/team-960w.webp 960w, /photos/team-1200w.webp 1200w"
    type="image/webp">
  <img
    src="/photos/team.jpg"
    srcset="/photos/team-320w.jpg 320w, /photos/team-640w.jpg 640w, /photos/team-960w.jpg 960w"
    sizes="(max-width: 960px) 100vw, 960px"
    alt="Team photo"
    width="1200"
    height="800">
</picture>

4. sizes heuristic — pageflare injects a default sizes value based on the image’s rendered width in the document. For images without a class or style that constrains their width, it defaults to (max-width: <width>px) 100vw, <width>px.

Tip

You can override the generated sizes attribute by adding it explicitly to your source HTML. pageflare does not overwrite an existing sizes attribute.

Configuration

{
  "platform_images": true
  // Breakpoints, formats, and quality are configured automatically
}

Lazy loading

Lazy loading for images is applied by the HTML lazy load processor, not by an image-specific processor. It adds loading="lazy" to <img> elements. See HTML processors for details on the exclude list and cautions around LCP images.

Related concepts

• HTML processors — lazy loading and srcset injection happen at the HTML layer
• Asset graph — tracks image→HTML relationships for batch processing
• Processors — how image processors fit into the processing chain