Weave Code
Statamic Responsive Images Laravel Package
spatie/statamic-responsive-images
Spatie's Responsive Images addon for Statamic CMS generates responsive image versions automatically, with a fieldtype for art direction and Glide presets driven by configurable breakpoints.
Responsive Images for Statamic
Frequently asked questions about Statamic Responsive Images
- How do I install spatie/statamic-responsive-images?
- Run composer require spatie/statamic-responsive-images inside your Statamic 4.0+ project. Publish the package config file so you can define the breakpoints used by the fieldtype and the responsive tag. After that, either add the responsive fieldtype to a blueprint or drop the tag into an existing template. There is no external service to sign up for, but the addon only does anything inside a Statamic installation.
- Does this package work in a plain Laravel app without Statamic?
- No. It is a Statamic-first addon that extends Statamic's asset pipeline and Glide image engine and registers a fieldtype, an Antlers tag, a Blade directive, and a GraphQL field. In a plain Laravel application there is nothing for it to hook into. For non-Statamic projects, use spatie/laravel-medialibrary, which inspired this package, or configure Glide presets directly.
- Which Statamic and Laravel versions does spatie/statamic-responsive-images support?
- The addon requires Statamic 4.0 or higher, and the v6 release adds support for Statamic v6 and Laravel 12. Addon major versions track Statamic majors, with breaking jumps visible across the v2, v5, and v6 releases. Pin the addon version that matches your Statamic install and re-test after every Statamic upgrade rather than floating on a loose constraint.
- How do I configure breakpoints for responsive images in Statamic?
- Breakpoints are defined in the breakpoints array of the package config file, and both the fieldtype and the responsive tag read from it. Each entry maps to a width used when building the srcset, so the array should mirror your actual design system. The defaults are Tailwind-flavoured, so review them instead of accepting them blindly. Changing breakpoints later means existing variants no longer match and should be regenerated.
- How do I render responsive images in Antlers, Blade, or GraphQL?
- In Antlers use the responsive tag, for example {{ responsive:image }}, against an asset field or a responsive fieldtype value. In Blade you can use the @responsive directive available from version 1.6.0. For headless or decoupled setups, the addon exposes a GraphQL responsive field. All three surfaces render the same breakpoint-driven srcset markup.
- Should I disable statamic.assets.image_manipulation.cache when using this addon?
- The documentation generally recommends setting statamic.assets.image_manipulation.cache to false so only images a browser actually requests are generated. With caching enabled you risk generating a large matrix of variants up front, especially combined with art direction breakpoints. The trade-off is that the first request for a given size is slower because the transform happens on demand. Pair either approach with a CDN or long cache headers if traffic is heavy.
- Does this addon support real art direction with different crops per breakpoint?
- Yes, that is the main reason to use the responsive fieldtype rather than a plain asset field. Options such as use_breakpoints, allow_ratio, and allow_fit let editors pick a focal crop and aspect ratio per breakpoint in the control panel. If you only need a basic srcset with no per-breakpoint cropping, the responsive tag on a normal asset field is enough.
- Can I use the responsive tag with existing asset fields without changing blueprints?
- Yes. The lowest-commitment adoption path is to add the responsive tag to one template pointing at an asset field you already have. No blueprint change and no data migration are involved, so you can validate breakpoint config, output markup, and performance first. The fieldtype stores asset references, so introducing it later also requires no content migration, though editorial workflows change for those fields.
- Do I need a queue worker or Horizon to generate responsive images?
- Generation can be pushed onto a queue, which requires real workers such as Horizon with Redis behind them. Without a queue the transforms run synchronously, which is fine for low upload volume but can slow down control panel saves or the first front-end request. Decide based on how many assets editors upload and whether on-demand generation delays are acceptable to you.
- Is spatie/statamic-responsive-images safe for a rendering-critical production path, and what are the alternatives?
- The code is thin and reliable, but this is a single-vendor package with roughly 115 stars and zero dependents, so third-party articles, bug reports, and Stack Overflow answers are scarce and Spatie's maintainers are effectively the only support channel. It is also tightly coupled to Glide, so swapping image engines removes the addon with it, and past releases have needed edge-case fixes around placeholders, ratio switching, AVIF/WEBP attributes, and small images. Pin the major version and re-test on each Statamic upgrade before trusting it in a critical template. Alternatives include hand-rolled Glide presets, spatie/laravel-medialibrary for non-Statamic Laravel work, or an external service such as Imgix or Cloudinary if you already pay for one.
Weaver
How can I help you explore Laravel packages today?