PHPackages                             timnarr/kirby-imagex - 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. timnarr/kirby-imagex

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

timnarr/kirby-imagex
====================

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

0.1.4(11mo ago)797.5k—7.1%[3 issues](https://github.com/timnarr/kirby-imagex/issues)1MITPHPPHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0CI failing

Since Feb 8Pushed 1mo ago4 watchersCompare

[ Source](https://github.com/timnarr/kirby-imagex)[ Packagist](https://packagist.org/packages/timnarr/kirby-imagex)[ Docs](https://github.com/timnarr/kirby-imagex)[ Fund](https://www.buymeacoffee.com/tim.n)[ RSS](/packages/timnarr-kirby-imagex/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (25)Used By (1)

[![Kirby Imagex Banner](/.github/imagex-banner.png)](/.github/imagex-banner.png)

Kirby Imagex
============

[](#kirby-imagex)

**Modern Images for Kirby CMS** – Imagex helps you orchestrate modern, responsive and performant images in Kirby.

Features
--------

[](#features)

- 🌠 Dynamic generation of image srcsets for art-directed or media-condition-based images.
- 📐 Helps you easily change the aspect ratio without the need to define new srcset presets.
- 😴 Supports native lazy loading and is customizable for JavaScript lazy loading libraries.
- 🚀 Improve the performance of your critical LCP (Largest Contentful Paint) images, utilizing `Priority Hints`.
- ⚡️ Supports multiple modern image formats, like AVIF and WebP.
- 🧩 Can easily be integrated as a snippet into existing blocks/projects.
- 🪄 Uses only Kirby's core capabilities for image handling.

Getting Started
---------------

[](#getting-started)

Four steps to get Imagex running:

1. [Install via Composer](#installation-via-composer)
2. [Set up Imagex global plugin config](#global-configuration)
3. [Adjust Kirby's thumbs config and add srcset presets](#adjust-kirbys-thumbs-config-and-add-srcset-presets)
4. [Configure and pass options to the Imagex snippet](#snippet-configuration-and-usage)

### Examples for Different Configurations and HTML Output

[](#examples-for-different-configurations-and-html-output)

You'll find all examples in the [examples.md](/docs/examples/README.md).

Installation via Composer
-------------------------

[](#installation-via-composer)

```
composer require timnarr/kirby-imagex

```

Global Configuration
--------------------

[](#global-configuration)

Configure global settings in your `config.php` file:

```
return [
  'timnarr.imagex' => [
    'cache' => true,
    'compareFormatsWeights' => 'mobile',
    'customLazyloading' => false,
    'formats' => ['avif', 'webp'],
    'addOriginalFormatAsSource' => false,
    'noSrcsetInImg' => false,
    'relativeUrls' => false,
  ],
];
```

### Global Options

[](#global-options)

OptionDefaultTypeDescription`cache``true`BooleanImagex will cache some calculations. Read more about it here: "[Cache](#cache)"`compareFormatsWeights``'mobile'`String or ArrayControls the weighting used when comparing format sizes via `compareFormats`. Preset strings: `'mobile'` (50/30/20), `'desktop'` (20/30/50), `'balanced'` (34/33/33). For custom weights pass an array: `['small' => 0.4, 'medium' => 0.4, 'large' => 0.2]` — values must sum to `1.0`. Read more: "[Dynamic Format Size Handling](#dynamic-format-size-handling)".`customLazyloading``false`BooleanImagex will initially use native lazy loading with the `loading` attribute. Enable this option if you want to use a custom lazy loading library like lazysizes or any other JS-based solution. Imagex will then automatically use `data-src` and `data-srcset`. If you need something like `data-sizes="auto"` please use the snippet options to add it as a lazy HTML attribute.`formats``['avif', 'webp']`Array with StringsDefine the modern image formats you want to use. ⚠️ Order matters here! You should go from the most to less modern format. The order in this array also affects the `compareFormats` snippet-option. [Read more about why the correct order is important](#why-order-matters). You **shouldn't add the original image format here** like PNG or JPEG.`addOriginalFormatAsSource``false`BooleanAdds a `` element for the image's original format (e.g. JPEG, PNG). Useful when modern formats like AVIF or WebP can't be used, but you still need art-directed picture sources at different breakpoints / media conditions.`noSrcsetInImg``false`BooleanIf active this will only output the `src` attribute in the `` tag. The smallest size from the given srcset-preset is used and the `srcset` attribute is omitted.`relativeUrls``false`BooleanOutput relative image URLs everywhere when active.Adjust Kirby's Thumbs Config and Add Srcset Presets
---------------------------------------------------

[](#adjust-kirbys-thumbs-config-and-add-srcset-presets)

The srcset configuration is still set up as you know it from Kirby, [like described here](https://getkirby.com/docs/reference/objects/cms/file/srcset#define-presets__extended-example).

Set your srcset preset, like `my-srcset`, and define only the `width` — no `height` needed. Imagex calculates the height from the `ratio` you pass to the snippet, so one preset works for any aspect ratio. Switching from `16/9` to `1/1` is a one-line change, no new presets needed.

If you use AVIF and/or WebP, add a separate preset per format by copying the base preset, appending `-{format}` to the name, and setting the `format` option. This gives you full control over quality per format.

The quality settings for the modern formats shouldn't simply be taken from the default preset. To really benefit from smaller image files due to modern formats, you should slightly adjust your quality settings. My rule of thumb is to take the quality value from JPEG/PNG and reduce it by 5 for WebP and 15 for AVIF. Here is a good [read](https://www.industrialempathy.com/posts/avif-webp-quality-settings/) with more detail, but I've also noticed that this isn't completely applicable to images in Kirby.

```
// config.php
'thumbs' => [
  'srcsets' => [
    'my-srcset' => [ // preset for JPEG and PNG
      '400w'  => ['width' =>  400, 'crop' => true, 'quality' => 80],
      '800w'  => ['width' =>  800, 'crop' => true, 'quality' => 80],
      '1200w' => ['width' => 1200, 'crop' => true, 'quality' => 80],
    ],
    'my-srcset-webp' => [ // preset for webp
      '400w'  => ['width' =>  400, 'crop' => true, 'quality' => 75, 'format' => 'webp', 'sharpen' => 10],
      '800w'  => ['width' =>  800, 'crop' => true, 'quality' => 75, 'format' => 'webp', 'sharpen' => 10],
      '1200w' => ['width' => 1200, 'crop' => true, 'quality' => 75, 'format' => 'webp', 'sharpen' => 10],
    ],
    'my-srcset-avif' => [ // preset for avif
      '400w'  => ['width' =>  400, 'crop' => true, 'quality' => 65, 'format' => 'avif', 'sharpen' => 25],
      '800w'  => ['width' =>  800, 'crop' => true, 'quality' => 65, 'format' => 'avif', 'sharpen' => 25],
      '1200w' => ['width' => 1200, 'crop' => true, 'quality' => 65, 'format' => 'avif', 'sharpen' => 25],
    ],
    // other srcset definitions
```

Snippet Configuration and Usage
-------------------------------

[](#snippet-configuration-and-usage)

Pass the file object of your image and other options to the Imagex snippet as follows:

```
// Define your options and pass them to the `imagex-picture` snippet

```

Imagex outputs a `` element with `` elements and one ``. If you need extra HTML you can wrap the Imagex snippet accordingly. Handle `svg` or `gif` files differently as needed!

```