PHPackages                             moritzebeling/kirby-headless-image-transformations - 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. moritzebeling/kirby-headless-image-transformations

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

moritzebeling/kirby-headless-image-transformations
==================================================

Kirby plugin for headless image transformations

1.0.1(3y ago)1043MITPHPPHP >=7.4.0

Since May 8Pushed 3y ago2 watchersCompare

[ Source](https://github.com/moritzebeling/kirby-headless-image-transformations)[ Packagist](https://packagist.org/packages/moritzebeling/kirby-headless-image-transformations)[ Docs](https://github.com/moritzebeling/kirby-headless-image-transformations)[ Fund](http://more.moritzebeling.com/support)[ RSS](/packages/moritzebeling-kirby-headless-image-transformations/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (1)Versions (2)Used By (0)

Kirby Headless Image Transformations
====================================

[](#kirby-headless-image-transformations)

This plugin adds a new route to your Kirby CMS installation that allows you to transform images on the fly. This is useful when you want to let the frontend decide what image size to load:

**Schema**

```
https://your-kirby-website.com/thumbs/{image-id}.{ext}?{transformations}

```

**Original image**

```
https://your-kirby-website.com/thumbs/{image-id}.{ext}

```

**Thumbnail with 640px width and auto height**

```
https://your-kirby-website.com/thumbs/{image-id}.{ext}?width=640

```

**Cropped thumbnail with 640px width and height**

```
https://your-kirby-website.com/thumbs/{image-id}.{ext}?width=640&height=640&crop=true

```

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

[](#installation)

```
composer require moritzebeling/kirby-headless-image-transformations
```

Or download/clone this repo into `site/plugins` of your Kirby project.

URL Query parameters
--------------------

[](#url-query-parameters)

You can use all options offered by the [Kirby `thumb()` method](https://getkirby.com/docs/reference/objects/cms/file/thumb#options):

```
let options = {
    'autoOrient' => true,  // bool
    'crop'       => false, // bool
    'blur'       => false, // bool
    'grayscale'  => false, // bool
    'height'     => null,  // int
    'quality'    => 90,    // int 0-100
    'width'      => null,  // int
}
```

Usage
-----

[](#usage)

This plugin can be helpful if you use Kirby as a Headless CMS and want to decide on your frontend which image size to load or to include in your srcset. You would only need the image id:

```
$image_id = $file->id();
```

**Load single size:**

```
function serializeObjectToQueryString( options = {} ){
    const queryString = Object.keys(options).map(key => key + '=' + options[key]).join('&');
    return queryString ? '?' + queryString : '';
}

const options = {
    width: 640,
    height: 640,
    crop: true,
};

const host = 'https://your-kirby-website.com/thumbs';
const image_id = 'page-id/image-filename.jpg';

const thumb_url = `${host}/${image_id}${serializeObjectToQueryString( options )}`;
```

```

```

**Load multiple widths for srcset:**

```
// createQueryString, url_base, image_id same as in example above

const sizes = [240,480,960];

let src = `${host}/${image_id}${serializeObjectToQueryString({ width: sizes[0] })}`;
let srcset = sizes.map( size => {
    const options = {
        width: size
    };
    return `${host}/${image_id}${serializeObjectToQueryString( options )} ${size}w`;
}).join(', ');
```

```

```

> Note that the html code above is just an example and wouln’t work in a vanilla setup, but require some type of templating engine, e.g. Svelte.

Options and security considerations
-----------------------------------

[](#options-and-security-considerations)

Whenever a thumbnail is requested for the first time, Kirby will generate it and store it in the `media` folder. So whenever a thumb is requested for the first time, it will take a little longer.

This also means that people with bad intentions could exploit this to overwhelm your server and fill up your disk space. In order to prevent this, you should restrict the allowed transformations to only the ones you actually need.

**Default settings:**

```
// site/config/config.php

return [
    'moritzebeling.headless-image-transformations' => [
        /*
        These values can either be:
        - false (not allowed, will be ignored and might fallback to Kirby's default settings)
        - true (any value is allowed, do not use in production)
        - array (list of allowed values)
        */
        'allowed' => [
            'autoOrient' => false,
            'crop'       => [true,false],
            'blur'       => false,
            'grayscale'  => false,
            'height'     => [40,80,160,240,360,480,640,720,960,1280,1440,1920,2560,3200],
            'quality'    => false,
            'width'      => [40,80,160,240,360,480,640,720,960,1280,1440,1920,2560,3200],
        ]
    ],
];
```

When sticking to the default options, it is only allowed to request thumbs with the specified widths and heights as well as cropping. If you need the other options, you should enable them via your `site/config/config.php` file.

You can also set some thumbnail option defaults for Kirby:

Development
-----------

[](#development)

1. Install a fresh Kirby StarterKit
2. `cd site/plugins`
3. `git clone` this repo

Roadmap:

- Discuss if preset images sizes make sense
- Check if browser caching works as expected

☕️ Support
----------

[](#️-support)

If you like this plugin, I would be glad if you would invite me for a coffee via [PayPal](http://more.moritzebeling.com/support). If you have any ideas for further development or stumble upon any problems, please open an issue or PR. Thank you!

Warranty
--------

[](#warranty)

This plugin is work in progress and comes without any warranty. Use at your own risk.

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

1098d ago

### Community

Maintainers

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

---

Top Contributors

[![moritzebeling](https://avatars.githubusercontent.com/u/39742729?v=4)](https://github.com/moritzebeling "moritzebeling (12 commits)")

---

Tags

headlesskirbypluginthumbnailtransformationsphppluginthumbnailimageresizeheadlesstransformthumbgenerationkirbykirby-pluginkirby-cms

### Embed Badge

![Health badge](/badges/moritzebeling-kirby-headless-image-transformations/health.svg)

```
[![Health](https://phpackages.com/badges/moritzebeling-kirby-headless-image-transformations/health.svg)](https://phpackages.com/packages/moritzebeling-kirby-headless-image-transformations)
```

###  Alternatives

[stefangabos/zebra_image

A single-file, lightweight PHP library designed for efficient image manipulation featuring methods for modifying images and applying filters

141110.4k6](/packages/stefangabos-zebra-image)[timnarr/kirby-imagex

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

797.5k1](/packages/timnarr-kirby-imagex)[reliqarts/laravel-guided-image

Simplified and ready image manipulation for Laravel via intervention image.

351.4k](/packages/reliqarts-laravel-guided-image)[moritzebeling/kirby-favicon

Kirby plugin to meet all favicon needs

144.8k](/packages/moritzebeling-kirby-favicon)[urlbox/screenshots

Use urlbox to easily generate website thumbnail screenshots from a URL

14250.4k](/packages/urlbox-screenshots)

PHPackages © 2026

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