PHPackages                             spatie/statamic-responsive-images - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. spatie/statamic-responsive-images

ActiveStatamic-addon[Utility & Helpers](/categories/utility)

spatie/statamic-responsive-images
=================================

Responsive Images for Statamic

6.2.0(2mo ago)115254.9k↓33.9%35MITPHPCI passing

Since Jan 10Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/spatie/statamic-responsive-images)[ Packagist](https://packagist.org/packages/spatie/statamic-responsive-images)[ RSS](/packages/spatie-statamic-responsive-images/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (8)Versions (94)Used By (0)

[![Latest Version](https://camo.githubusercontent.com/18840d6978c856d2abafbfe9df882a2591407d48f5f8ee6b8b22507e6fb42e51/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f7370617469652f73746174616d69632d726573706f6e736976652d696d616765732e7376673f7374796c653d666c61742d737175617265)](https://github.com/spatie/statamic-responsive-images/releases)[![Statamic 4.0+](https://camo.githubusercontent.com/bf09e15100bc65c9e433232cdc251788cbeabc3229091efa0145fd6fc619ccff/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53746174616d69632d342e302b2d4646323639453f7374796c653d666c61742d737175617265266c696e6b3d68747470733a2f2f73746174616d69632e636f6d)](https://camo.githubusercontent.com/bf09e15100bc65c9e433232cdc251788cbeabc3229091efa0145fd6fc619ccff/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53746174616d69632d342e302b2d4646323639453f7374796c653d666c61742d737175617265266c696e6b3d68747470733a2f2f73746174616d69632e636f6d)

Responsive Images
=================

[](#responsive-images)

> Responsive Images for Statamic CMS.

This Addon provides responsive images inspired by [Our Medialibrary Package](https://github.com/spatie/laravel-medialibrary).

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/9af952d775433b01785d4b8aa059f45e6d2bd3acb8ac703be8cac20bf94419c9/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f73746174616d69632d726573706f6e736976652d696d616765732e6a70673f743d31)](https://spatie.be/github-ad-click/statamic-responsive-images)

We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).

Installation
------------

[](#installation)

Require it using Composer.

```
composer require spatie/statamic-responsive-images

```

Fieldtype
---------

[](#fieldtype)

This addon includes a fieldtype that allows for full Art direction with responsive images.

[![fieldtype](./docs/fieldtype.png)](./docs/fieldtype.png)

This fieldtype is configured with the following yaml configuration:

```
-
    handle: image
    field:
      use_breakpoints: true
      allow_ratio: true
      allow_fit: true
      breakpoints:
        - sm
        - md
        - lg
      display: Image
      instructions: 'Choose image using art direction.'
      type: responsive
      icon: assets
      listable: hidden
      container: assets
      restrict: false
      allow_uploads: true
```

The configuration above can be used within Antlers using the responsive tag:

```
{{ responsive:image }}
```

The breakpoints are configured in the `breakpoints` array of the config file.

Using Responsive Images
-----------------------

[](#using-responsive-images)

Responsive Images will generate responsive versions of the images whenever a new asset is uploaded. These presets are determined by this package and not by your own Glide presets.

We generally recommend setting `statamic.assets.image_manipulation.cache` to `false` so only images actually requested by a browser are generated. The first time the conversion is loaded will be slow, but Glide still has an internal cache that it will serve from the next time. This saves a lot on server resources and storage requirements.

Templating
----------

[](#templating)

Pass an image to the `responsive` tag.

```
{{ responsive:image_field }}
```

This will render an image tag with the default srcsets. The tag uses JS to define the value of the sizes attribute. This way the browser will always download the correct image.

Image ratio
-----------

[](#image-ratio)

You can make sure images are a certain ratio by passing a `ratio` parameter, either as a string `16/10` or as a float `1.6`.

```
{{ responsive:image_field ratio="16/9" }}
```

Responsive placeholder
----------------------

[](#responsive-placeholder)

By default, responsive images generates a small base64 encoded placeholder to show while your image loads. If you want to disable this you can pass `placeholder="false"` to the tag.

```
{{ responsive:image_field placeholder="false" }}
```

Additional image format generation
----------------------------------

[](#additional-image-format-generation)

By default, responsive tag generates original source image file format and WEBP variants of the image, so if you use a JPG image as source then by default JPG and WEBP variants will be generated. You can toggle WEBP and AVIF variant generation with the tag parameters.

```
{{ responsive:image_field webp="true" avif="false" }}
```

You can also toggle this in responsive-images.php config file, it will apply your preferences globally.

```
'webp' => true,
'avif' => false,
```

Image quality
-------------

[](#image-quality)

Image format quality settings can be set globally through config. If you wish to override the config quality values you can use tag parameters. You can utilize breakpoints for the quality parameter too!

```
{{ responsive:image_field quality:webp="50" md:quality:webp="75" }}
```

Glide parameters
----------------

[](#glide-parameters)

You can still pass any parameters from the Glide tag that you would want to, just make sure to prefix them with `glide:`. Passing `glide:width` will consider the width as a max width, which can prevent unnecessary large images from being generated.

```
{{ responsive:image_field glide:blur="20" glide:width="1600" }}
```

HTML Attributes
---------------

[](#html-attributes)

If you want to add additional attributes (for example a title attribute) to your image, you can add them as parameters to the tag, any attributes will be added to the image.

```
{{ responsive:image_field alt="{title}" class="my-class" }}
```

Breakpoints & Art direction
-------------------------------

[](#breakpoints--art-direction)

You can define breakpoints in the config file, by default the breakpoints of TailwindCSS are used.

Breakpoints allow you to use, for example, different ratios:

```
{{ responsive:image_field ratio="1/1" lg:ratio="16/9" 2xl:ratio="2/1" }}
```

This will apply a default ratio of `1/1`. From breakpoint `lg` up to `2xl`, the ratio will be `16/9`. From `2xl` up, the ratio will be `2/1`. The breakpoints can be configured in the config and default to the breakpoints of Tailwind CSS.

Or different assets:

```
{{ responsive:image_field :lg:src="image_field_lg" :2xl:src="image_field_2xl" }}
```

Breakpoints support the `ratio`, `src`, `quality` and `glide` parameters.

Customizing the generated html
------------------------------

[](#customizing-the-generated-html)

If you want to customize the generated html, you can publish the views using

```
php artisan vendor:publish
```

and choosing `Spatie\ResponsiveImages\ServiceProvider`

Generate command
----------------

[](#generate-command)

If you need to regenerate the responsive images for a reason, you can use the `regenerate` command which will clear the Glide cache and regenerate the versions. This command only works when you have the `statamic.assets.image_manipulation.cache` config option set to `true` (which we generally don't recommend).

```
php please responsive:regenerate
```

If you are using a service, like Horizon, for queues then jobs will be queued to handle the image resizing. By default, the job is queued under the 'default' queue. This can be changed via the `queue` config key under `responsive-images.php`

It is also possible to exclude certain containers from generation responsive variants. You can exclude these containers by adding the handle of the container to the `excluded_containers` array in `responsive-images.php`.

GraphQL
-------

[](#graphql)

This addon comes with 2 GraphQL goodies, it adds a `responsive` field to assets and responsive fieldtype, allowing you to use this addon like you would with the Antlers tag. Secondly you can just let responsive fieldtype augment itself without passing any arguments.

### Responsive field on assets / assets fieldtype / responsive fieldtype

[](#responsive-field-on-assets--assets-fieldtype--responsive-fieldtype)

You can retrieve a responsive version of an `image` asset fieldtype like this:

```
{
  entries {
    data {
      id,
      image {
        responsive(ratio: 1.2) {
          label
          minWidth
          widthUnit
          ratio
          sources {
            format
            mimeType
            minWidth
            mediaWidthUnit
            mediaString
            srcSet
            placeholder
          }
        }
      }
    }
  }
}
```

Majority of tag parameters are available as arguments in the responsive field, the parameters just need to have colons replaced with underscores. For example, `lg:glide:filter` would become `lg_glide_filter`.

If you are unsure what arguments are available, try out the GraphQL explorer in the control panel located at `/cp/graphiql` and utilize the autocomplete feature.

### Images from the responsive fieldtype

[](#images-from-the-responsive-fieldtype)

A responsive fieldtype has all the same fields as a normal responsive field from an asset, except they're under a `breakpoints` key and you cannot pass any arguments to it.

```
{
  entries {
    data {
      id,
      art_image {
        breakpoints {
          label
          minWidth
          widthUnit
          ratio
          sources {
            format
            mimeType
            minWidth
            mediaWidthUnit
            mediaString
            srcSet
            placeholder
          }
        }
      }
    }
  }
}
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Rias Van der Veken](https://github.com/riasvdv)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

63

—

FairBetter than 99% of packages

Maintenance87

Actively maintained with recent releases

Popularity51

Moderate usage in the ecosystem

Community28

Small or concentrated contributor base

Maturity73

Established project with proven stability

 Bus Factor1

Top contributor holds 54.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~26 days

Recently: every ~136 days

Total

88

Last Release

66d ago

Major Versions

v1.8.0 → v2.0.02021-01-25

2.x-dev → v3.0.02023-02-04

v3.1.3 → v4.0.02023-05-13

v4.1.1 → v5.0.02024-05-13

v5.2.2 → 6.0.02026-02-13

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

![](https://www.gravatar.com/avatar/dbd355ba9a931da845b0c4ff59a974dab98f829d567bb8c5ff435c823dfa255e?d=identicon)[riasvdv](/maintainers/riasvdv)

---

Top Contributors

[![riasvdv](https://avatars.githubusercontent.com/u/3626559?v=4)](https://github.com/riasvdv "riasvdv (169 commits)")[![ncla](https://avatars.githubusercontent.com/u/5507083?v=4)](https://github.com/ncla "ncla (60 commits)")[![aerni](https://avatars.githubusercontent.com/u/23167701?v=4)](https://github.com/aerni "aerni (24 commits)")[![heidkaemper](https://avatars.githubusercontent.com/u/10990014?v=4)](https://github.com/heidkaemper "heidkaemper (12 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (8 commits)")[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (8 commits)")[![gofish543](https://avatars.githubusercontent.com/u/10394554?v=4)](https://github.com/gofish543 "gofish543 (3 commits)")[![kevinmeijer97](https://avatars.githubusercontent.com/u/9716909?v=4)](https://github.com/kevinmeijer97 "kevinmeijer97 (3 commits)")[![joetannenbaum](https://avatars.githubusercontent.com/u/2702148?v=4)](https://github.com/joetannenbaum "joetannenbaum (2 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![hgrimelid](https://avatars.githubusercontent.com/u/40372?v=4)](https://github.com/hgrimelid "hgrimelid (1 commits)")[![jackmcdade](https://avatars.githubusercontent.com/u/44739?v=4)](https://github.com/jackmcdade "jackmcdade (1 commits)")[![JeremyDunn](https://avatars.githubusercontent.com/u/161614?v=4)](https://github.com/JeremyDunn "JeremyDunn (1 commits)")[![GertTimmerman](https://avatars.githubusercontent.com/u/6702926?v=4)](https://github.com/GertTimmerman "GertTimmerman (1 commits)")[![dgjorgjiev-snk](https://avatars.githubusercontent.com/u/100845860?v=4)](https://github.com/dgjorgjiev-snk "dgjorgjiev-snk (1 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (1 commits)")[![micahhenshaw](https://avatars.githubusercontent.com/u/31399816?v=4)](https://github.com/micahhenshaw "micahhenshaw (1 commits)")[![mpskovvang](https://avatars.githubusercontent.com/u/7034075?v=4)](https://github.com/mpskovvang "mpskovvang (1 commits)")[![BobWez98](https://avatars.githubusercontent.com/u/23509926?v=4)](https://github.com/BobWez98 "BobWez98 (1 commits)")[![quintenbuis](https://avatars.githubusercontent.com/u/36452184?v=4)](https://github.com/quintenbuis "quintenbuis (1 commits)")

---

Tags

hacktoberfest

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/spatie-statamic-responsive-images/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-statamic-responsive-images/health.svg)](https://phpackages.com/packages/spatie-statamic-responsive-images)
```

###  Alternatives

[statamic/seo-pro

68516.6k](/packages/statamic-seo-pro)[statamic-rad-pack/runway

Eloquently manage your database models in Statamic.

135224.7k7](/packages/statamic-rad-pack-runway)[rias/statamic-redirect

29335.6k](/packages/rias-statamic-redirect)[duncanmcclean/statamic-cargo

Comprehensive e-commerce addon for Statamic. Build bespoke e-commerce sites without the complexity.

3416.9k](/packages/duncanmcclean-statamic-cargo)[jacksleight/statamic-bard-texstyle

18195.4k](/packages/jacksleight-statamic-bard-texstyle)[marcorieser/statamic-livewire

A Laravel Livewire integration for Statamic.

23111.5k14](/packages/marcorieser-statamic-livewire)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)