Download the PHP package massif/statamic-responsive-images without Composer

Responsive Images

A production-ready Statamic 6 addon that renders responsive <picture> elements from a single Antlers tag. Format negotiation (AVIF → WebP → fallback) is handled by the browser, intrinsic dimensions are always set to prevent CLS, and a tiny inline LQIP is rendered behind the image while it loads.

Srcset generation follows the next/image model: a pool of candidate widths built from device_sizes ∪ image_sizes, capped at the source image's intrinsic width.

Requirements

• PHP 8.2+
• Statamic 6
• Statamic Glide enabled (default)

Installation

The addon auto-registers via its service provider. Publish the config if you want to tweak defaults:

Quickstart

Output (simplified):

With an asset field:

Parameters

Classes

class targets the outermost rendered element. When you wrap the output in a <figure> or a ratio <div>, the class lands on that wrapper; otherwise it lands on the <img>. If you also pass img_class in the wrapperless case, both are merged on the <img>.

Captions

In figure mode, the tag auto-captions from the resolved alt text (which itself falls back to the asset's alt field). Explicit caption wins. Pass caption="false" to render a <figure> without a <figcaption>.

Focal point → object-position

When the source is a Statamic asset with a focal point set in the CP, the tag emits an inline object-position: x% y% on the <img> so CSS-cropped layouts (e.g. object-fit: cover on a fixed-aspect container) keep the subject in frame. This is on by default, is a no-op when no focal point is set, and costs nothing when the CSS doesn't use object-fit.

Tag alias

For brevity, the addon ships a short alias {{ pic }} alongside the canonical {{ responsive_image }}. Both tags share every behavior, parameter, and wildcard form:

The alias handle is configurable:

Wildcard form

Resolve src from the template context by field name:

The tag suffix (after the :) is read from $this->context, so any field, augmented asset, or template variable on the current scope is usable.

Preload

For above-the-fold images (LCP candidates), set preload="true":

The tag pushes a <link rel="preload" as="image" imagesrcset=… imagesizes=… type="image/avif" fetchpriority="high"> onto the Antlers head stack. Statamic's default head partial (vendor/statamic/cms/resources/views/partials/head.blade.php) already renders that stack, so preload works out of the box on a stock layout.

If you've replaced the default head partial with a fully custom one, make sure it still renders the stack:

When the stack is absent, Statamic silently discards the push — no error, but also no preload link in the output.

When preload="true" is set, the tag also:

• Sets loading="eager" on the <img> (unless you passed loading="..." explicitly).
• Sets fetchpriority="high" on the <img> (unless you passed fetchpriority="..." explicitly).

Both auto-behaviors are togglable in config:

Format selection. The preload link targets the highest-priority enabled format (AVIF → WebP → fallback). Browsers that can't decode the format (e.g. older browsers on an AVIF link) skip the preload — safe, because type= is set.

Limitations.

• Per-breakpoint preload for art-directed sources is not supported in v1 — the preload targets the primary src.
• Needs a rendered head stack in your layout. Statamic's default partial provides this; only custom layouts that omit it would need to wire it in manually.

SVG and GIF

SVG (image/svg+xml) and GIF (image/gif) sources skip the Glide pipeline entirely. The tag emits a plain <img> with the original URL, width/height from metadata when available, class, loading, decoding, and aria-hidden="true" when alt is empty. No <picture>, no srcset, no re-encoding — raster transforms would either produce meaningless output (SVG) or lose animation (GIF).

Glide passthrough params (blur, sharpen, etc.) are ignored for these sources.

Art direction

Pass an array of entries via the sources parameter. Each entry becomes its own block of <source> elements with the given media query. Entries earlier in the array win (the browser picks the first matching <source>).

Antlers limitation — sources must be a variable, not an inline literal. Antlers' expression parser chokes on inline array literals whose string values contain colons (e.g. (max-width: 768px)), so you cannot pass :sources="[{...}]" directly in a template. Build the array outside the template and pass it by name. The cleanest options:

1. Blueprint field. Add a replicator or grid field called image_sources with src, media, sizes, and ratio subfields, then:

2. Template variable via a view composer, augmenter, or controller. Share a hero_sources array from PHP and reference it the same way:

Each entry accepts src (required), media, sizes, and ratio. The last entry's src is used as the <img> fallback when no breakpoint matches.

Source inheritance. An art-direction source may omit src to reuse the parent image with a different crop, ratio, or focal point per breakpoint:

Config

config/responsive-images.php:

device_sizes vs image_sizes. Device sizes cover full-width images at common device breakpoints. Image sizes cover small images (thumbnails, icons). The final srcset pool is their union, deduped, sorted, and capped at the source image's intrinsic width — the browser then picks the best candidate based on sizes.

Format quality. AVIF defaults to 50, WebP to 75, fallback to 82. Lower values ship smaller bytes; tune per project.

Placeholder integration with daun/statamic-placeholders. If you install the daun/statamic-placeholders addon, its placeholder data (ThumbHash, BlurHash, or Average color — whichever you've configured on the asset's placeholder field) is auto-detected and used in preference to the built-in Glide LQIP. When the asset has no placeholder data or when src is a raw URL, we silently fall back to the Glide LQIP — output shape is unchanged (still a base64 data URI on background-image). Provider choice lives entirely in that addon; we don't expose a provider knob, since mismatching our override against the blueprint's placeholder_type would silently miss and fall back. Disable the integration by setting placeholder.statamic_placeholders.enabled to false.

Automatic format support detection

By default the addon only emits an <avif> or <webp> <source> when the active imaging driver (statamic.assets.image_manipulation.driver) can actually encode it, probed via Statamic's ImageValidator. This prevents broken images on servers whose GD/Imagick lacks a format — a <picture> element does not fall back when a <source> fails to load. Disable with formats.detect_support => false (e.g. when a transform-CDN serves formats your local driver can't).

The per-format formats.avif.enabled / formats.webp.enabled flags still apply and are ANDed with detection.

Skipping modern formats for small images

Set formats.min_width (default 0, disabled) to a pixel width below which AVIF/WebP are skipped in favor of the fallback — the modern-format overhead rarely pays off on tiny thumbnails. AVIF is additionally never emitted below libavif's hard 16px floor (this is always on; it fixes 0-byte AVIF variants at tall aspect ratios).

Placeholders

• LQIP (placeholder.enabled) — a tiny blurred inline data-URI.
• Dominant color (placeholder.color.enabled, default on) — the image's average color painted as the <img> background-color, shown under the LQIP (and alone if the LQIP is off). Both are suppressed by placeholder="false" on the tag.

sizes="auto"

Lazy images get sizes="auto, …" prepended (WHATWG auto-sizes) so the browser derives the displayed size from layout; older browsers ignore the token. Disable with markup.auto_sizes => false.

Metadata stripping

strip_metadata => true (default false) strips EXIF/ICC/XMP/IPTC on encode. It is a global Glide manipulator affecting every image on the site and discards copyright/EXIF, so it is opt-in. Imagick only.

Performance notes

• Metadata is cached by {prefix}:meta:{id}:{mtime}. Changing the source file invalidates automatically.
• LQIPs are cached by {prefix}:lqip:{id}:{mtime} and inlined as a base64 data URI (no extra request).
• Glide does the heavy lifting — transformed variants are cached on disk by Statamic's Glide pipeline. Cold requests do the work once.
• No Accept sniffing. Format negotiation is entirely browser-side via <picture>, so the response is cacheable by any CDN.

Caveats

• AVIF encoding is slow. First request per (image, width) can take a few seconds. Warm critical pages at deploy time if this matters.

• AVIF requires Imagick with libheif or a recent GD build. If your image driver can't emit AVIF, disable it:

• Non-image assets are skipped. Unresolvable src values log a warning and render nothing.
• Plain URL src values bypass mtime-based cache invalidation. Only Statamic assets (assets::id or asset instances) carry an mtime; URL strings cache under a zero mtime, so replacing a file at the same URL will not invalidate metadata or LQIPs. Clear the cache manually (or bump the config cache.prefix) after such replacements.
• Missing alt text is logged but does not throw. Fix the warning or pass alt="" explicitly for decorative images.
• Color profiles are normalized to sRGB on the Imagick driver with the lcms delegate. Source images in Adobe RGB, Display P3, or CMYK are color-managed (not blindly tagged) so the browser gets true sRGB output. The manipulator silently no-ops on GD, non-Imagick drivers, and Imagick builds without lcms — delivery continues unchanged in those cases. Confirm lcms availability with convert -list configure | grep DELEGATES. After upgrading, clear storage/statamic/glide so existing cached transforms get regenerated with the profile applied.

License

MIT