PHPackages                             nerdcel/kirby3-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. [Image & Media](/categories/media)
4. /
5. nerdcel/kirby3-responsive-images

ActiveKirby-plugin[Image & Media](/categories/media)

nerdcel/kirby3-responsive-images
================================

Kirby3 plugin to manage responsive images settings using the panel.

v3.4.2(1mo ago)92.2k2MITPHPPHP >= 8.1 < 8.5

Since Jan 25Pushed 3d ago2 watchersCompare

[ Source](https://github.com/nerdcel/kirby3-responsive-images)[ Packagist](https://packagist.org/packages/nerdcel/kirby3-responsive-images)[ Docs](https://github.com/nerdcel/kirby3-responsive-images)[ RSS](/packages/nerdcel-kirby3-responsive-images/feed)WikiDiscussions main Synced 1w ago

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

Responsive Images Plugin
========================

[](#responsive-images-plugin)

[![GitHub release](https://camo.githubusercontent.com/e5db20f97f270cfbb0478b3c011ae5533192112240a0fb8e60afafafc48cb614/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6e65726463656c2f6b69726279332d726573706f6e736976652d696d616765732e737667)](https://camo.githubusercontent.com/e5db20f97f270cfbb0478b3c011ae5533192112240a0fb8e60afafafc48cb614/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6e65726463656c2f6b69726279332d726573706f6e736976652d696d616765732e737667)[![License](https://camo.githubusercontent.com/83e516e87a9474a6914fe229cd610a00670e0072cc405bb290065fb9e6a8bb98/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6e65726463656c2f6b69726279332d726573706f6e736976652d696d616765732e737667)](https://camo.githubusercontent.com/83e516e87a9474a6914fe229cd610a00670e0072cc405bb290065fb9e6a8bb98/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6e65726463656c2f6b69726279332d726573706f6e736976652d696d616765732e737667)[![Kirby 4+](https://camo.githubusercontent.com/016d1888f4bf7c902d7fa3ca9aff34cd3d62cebf4840b0534eb01c27f3c4b93c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4b697262792d342532422d303061326564)](https://camo.githubusercontent.com/016d1888f4bf7c902d7fa3ca9aff34cd3d62cebf4840b0534eb01c27f3c4b93c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4b697262792d342532422d303061326564)

[![Responsive Images Plugin](docs/panel.png)](docs/panel.png)

This plugin provides functionality to generate responsive images in your Kirby CMS projects.

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

[](#installation)

1. **Using Composer**: ```
    composer require nerdcel/kirby3-responsive-images
    ```
2. **Manually**: Download the [latest release](https://github.com/nerdcel/kirby3-responsive-images/releases/latest)and copy the contents of the into your `site/plugins/responsive-images` folder.

Configuration
-------------

[](#configuration)

You can configure the plugin by adding the following options to your `config.php` file. Consider using the "ready" hook inside the kirby config if you are calling the kirby() function to set the configPath.

```
'ready' => function ($kirby) {
    return [
        'nerdcel.responsive-images' => [
            'configPath' => kirby()->root('content'),
            'configFile' => 'responsive-img.json',
            'quality' => 75,
            'defaultWidth' => 1024,
            'allowedRoles' => ['admin'],
        ],
    ];
}
```

If you open the panel now, the plugin should have generated an empty json file with the following content:

```
{"breakpoints": [], "settings": []}
```

Usage
-----

[](#usage)

Generating Responsive Images To generate a responsive image, use the makeResponsiveImage method:

```
use Nerdcel\ResponsiveImages\ResponsiveImages;
use Kirby\Cms\File;

$responsiveImages = ResponsiveImages::getInstance();
$imageTag = $responsiveImages->makeResponsiveImage(
    'settings-slug',
    $file, // instance of Kirby\Cms\File
    'custom-classes',
    true, // lazy loading
    'Alt text',
    'webp'
);

echo $imageTag;
```

But there is also a helper function that you can use to generate responsive images:

```
echo responsiveImage('settings-slug', $file, 'custom-classes', true, 'Alt text', 'webp');
```

Focal Point
-----------

[](#focal-point)

You can set the focal point(s) of an image for different viewports by adding the following fields to the image file blueprint:

```
...
fields:
  focalpoints:
    label: Focal Points override
    type: focalpoints
```

[![Focal points](docs/focalpoint-default.png)](docs/focalpoint-default.png)

AI Hint
-------

[](#ai-hint)

You can mark files as AI generated and let editors display a configurable hint text overlay on top of the responsive image. Add the `aihint` field to the file blueprint:

```
...
fields:
  aihint:
    label: AI hint
    type: aihint
    text: AI generated image      # default text, overridable by the editor
    position: bottom-right        # default position: top-left, top-right, bottom-left, bottom-right
    color: '#ffffff'               # default font color, overridable by the editor
    size: 5                        # default text size as % of the image height (1-15), overridable by the editor
    opacity: 100                   # default text/backdrop opacity in percent (0-100)
    margin: 0.6                    # default distance between the hint box and the image edge, in em (0-5)
    padding: 0.5                   # default space between the hint text and its backdrop box, in em (0-2)
```

Editors can enable the hint per file, override the text, choose the position (native select), font color (color picker), text size (slider, 1-15% of the image height), opacity (slider, 0-100%), the edge margin (slider, 0-3em) and the backdrop padding (slider, 0-2em) directly in the panel using Kirby's native toggle, text, select, color and range inputs. The AI hint field itself shows a live preview directly on the image that reacts instantly to every input change, and the focal points field also shows the same accurate preview on top of the real image. The backdrop box has rounded corners and its background color is chosen automatically (black or white) to contrast with the chosen font color, both in the panel preview and in the final burned-in image. Any option left untouched by the editor falls back to the blueprint defaults, which in turn fall back to the plugin's global configuration. The values are stored as plain YAML in the content file, just like Kirby's own structure/object fields (no JSON involved):

```
'ready' => function ($kirby) {
    return [
        'nerdcel.responsive-images' => [
            'aiHint' => [
                'text' => 'AI generated image',
                'position' => 'bottom-right',
                'color' => '#ffffff',
                'size' => 5,
                'opacity' => 100,
                'margin' => 0.6,
                'padding' => 0.5,
            ],
        ],
    ];
}
```

When enabled, editors get a live preview of the hint (text, position, color, size, opacity, margin and padding) directly in the panel while editing the `aihint` field and the focal points field. The font size scales proportionally to the rendered image **height** (using CSS container query block-size units) according to the editor-selected percentage (1-15%, defaulting to 5%), so it stays legible and consistently proportioned across every responsive breakpoint.

The hint is **not** rendered as an HTML overlay on the frontend — `responsiveImage()` / `makeResponsiveImage()` output plain ``/`` markup without any extra wrapper or span. Instead, the hint is only ever conveyed on the frontend by being burned directly into the generated image itself (see below), so there is no separate stylesheet to include.

### Compliance: the hint is burned into the image, not styled with CSS

[](#compliance-the-hint-is-burned-into-the-image-not-styled-with-css)

A pure CSS overlay can be removed or hidden, and disappears once the image is downloaded or reused elsewhere — which isn't sufficient to satisfy AI content labelling obligations (e.g. Art. 50 of the EU AI Act). To cover this, every generated thumbnail is **stamped**:

- The hint text is burned directly into the image's pixel data (position, color and proportional size follow the same settings as the overlay), so it stays visible even if the image is saved, shared or embedded outside of your site.
- For JPEGs, basic IPTC IIM metadata (keywords `AI-generated` / `KI-generiert` and a caption with the hint text) is embedded into the file as well, so the marking survives in the file itself and is readable by photo/asset management tools.
- Additionally, an XMP metadata packet is embedded into **JPEG, PNG and WebP** output (a `dc:description`with the hint text, plus the IPTC `DigitalSourceType` set to `trainedAlgorithmicMedia`). Unlike the legacy IPTC IIM block above, XMP isn't limited to JPEG, so this also covers PNG and WebP thumbnails. GIF and AVIF currently only get the burned-in pixels, without embedded metadata.

Stamped copies are generated once and cached alongside the regular thumbnail; they're automatically regenerated if you change the hint text, position, color, size, opacity, margin or padding. By default, a common regular-weight system font (e.g. DejaVu Sans, Arial) is used for the burned-in text, matching the panel preview's normal font weight; you can point to your own `.ttf` file via the `font` option:

```
'nerdcel.responsive-images' => [
    'aiHint' => [
        // ...
        'font' => '/path/to/your-font.ttf',
    ],
],
```

When using `makeResponsiveImageObject()` / `responseType: 'json'`, the returned object includes an additional `aiHint` key (`{ text, position, color, size, opacity, margin, padding }` or `null` when disabled) so you can render your own overlay markup.

License This plugin is licensed under the MIT License. See the LICENSE file for more details.

###  Health Score

56

—

FairBetter than 97% of packages

Maintenance95

Actively maintained with recent releases

Popularity26

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 95.7% 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 ~32 days

Recently: every ~61 days

Total

40

Last Release

46d ago

Major Versions

1.2.1 → 2.0.02023-11-15

2.1.0 → 3.0.0-alpha.02024-12-04

v2.x-dev → 3.0.0-alpha.22024-12-18

2.1.2 → 3.0.0-alpha.4.12025-01-16

PHP version history (3 changes)1.0.1PHP >= 8.0 < 8.2

2.1.0-alpha-1PHP >= 8.1 < 8.4

v3.4.0PHP >= 8.1 < 8.5

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3840331?v=4)[Marcel Hieke](/maintainers/nerdcel)[@nerdcel](https://github.com/nerdcel)

---

Top Contributors

[![nerdcel](https://avatars.githubusercontent.com/u/3840331?v=4)](https://github.com/nerdcel "nerdcel (89 commits)")[![JarekYaro](https://avatars.githubusercontent.com/u/53605886?v=4)](https://github.com/JarekYaro "JarekYaro (2 commits)")[![yarekpietrasina](https://avatars.githubusercontent.com/u/53605886?v=4)](https://github.com/yarekpietrasina "yarekpietrasina (2 commits)")

---

Tags

image-processingkirby-cmskirby-pluginkirby4kirby5responsive-imageskirbykirby-pluginkirby-cmsgetkirby

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/nerdcel-kirby3-responsive-images/health.svg)

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

###  Alternatives

[getkirby/cms

The Kirby core

1.5k606.6k541](/packages/getkirby-cms)[medienbaecker/kirby-modules

Easily add modules to your pages

895.6k1](/packages/medienbaecker-kirby-modules)[timnarr/kirby-imagex

Modern images for Kirby CMS – This plugin helps you orchestrate modern, responsive and performant images in Kirby

828.9k1](/packages/timnarr-kirby-imagex)[bnomei/kirby3-janitor

Kirby Plugin for running commands like cleaning the cache from within the Panel, PHP code or a cronjob

9343.5k2](/packages/bnomei-kirby3-janitor)[bnomei/kirby3-feed

Generate a Atom/JSON/RSS-Feed and XML-Sitemap from Pages-Collections

7228.0k](/packages/bnomei-kirby3-feed)[bnomei/kirby3-dotenv

Kirby Plugin for environment variables from .env

4151.3k2](/packages/bnomei-kirby3-dotenv)

PHPackages © 2026

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