moinframe/kirby-image-snippet

Snippet + Helper Methods for handling images in Kirby

2.0.0 2026-01-31 09:33 UTC

Requires

• getkirby/cms: ^4.0 || ^5.0
• getkirby/composer-installer: ^1.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.62
• mockery/mockery: ^1.6
• pestphp/pest: ^3.0
• phpunit/phpunit: ^11.0

Suggests

• srwiez/thumbhash: ^1.4 - For enhanced placeholder image generation with ThumbHash

MIT

• Justus Kraft

• kirby-plugin

Published on Packagist.org on 2026-07-21 08:43 UTC

README

Snippet + Helper methods for handling images in Kirby 4+.

Installation

Install via composer

To use the snippet and helper methods you need to require this package via composer.

composer require moinframe/kirby-image-snippet

Usage

Snippet

<?php snippet('image', ['image' => $page->images()->first()]); ?>

Field methods

<div data-cover='<?= $page->images()->first()->toImageInterface()->toJson(); ?>' data-images='<?= $page->images()->toImageInterfaces()->toJson(); ?>'></div>

Options

You can override the default options on a per image basis.

<?php snippet('image', ['image' => $page->images()->first(), 'ratio' => 1, 'dimensions' => [200]]); ?>

<div data-cover='<?= $page->images()->first()->toImageInterface(['ratio' => 1, 'dimensions' => [200]])->toJson(); ?>'></div>

Attributes

You can pass additional HTML attributes to the <img> element via attrs and to the <picture> element via pictureAttrs. Both accept an array (rendered and escaped through Kirby's attr() helper) or a raw string (used as-is, not escaped).

<?php snippet('image', [
  'image' => $page->images()->first(),
  'attrs' => ['class' => 'my-image', 'data-foo' => 'bar'], // added to <img>
  'pictureAttrs' => ['class' => 'my-picture'],             // added to <picture>
]); ?>

<?php snippet('image', [
  'image' => $page->images()->first(),
  'attrs' => 'class="my-image" data-foo="bar"',
]); ?>

Fetch Priority

Set fetchpriority to hint the browser about loading priority — e.g. high for an above-the-fold LCP image (typically combined with lazy => false).

<?php snippet('image', ['image' => $page->images()->first(), 'lazy' => false, 'fetchpriority' => 'high']); ?>

Lazy Loading

You can activate lazy loading by defining lazy => true inside the options. The snippet will then add data-lazyload to the picture element and add the srcset as data-srcset to each <source>. You then have to use your own javascript implementation to lazyload the images.

Note: With lazy loading enabled the <img> also receives the native loading="lazy" attribute alongside the data-srcset hook. Because the real sources live in data-srcset, native lazy loading only applies to the tiny placeholder src and won't conflict with your JavaScript lazyloader.

Configuration

Default

You can override the default configuration in your websites site/config.php.

<?php

return [
  'moinframe.image-snippet' => [
    'placeholder' => [
        'width' => 50,
        'blur' => 10,
        'quality' => 50
    ],
    'ratio' => 0,
    'quality' => 80,
    'blur' => 0,
    'grayscale' => false,
    'lazy' => false,
    'formats' => ['avif', 'webp'],
    'dimensions' => [400, 800, 1140],
    'sizes' => '100vw',
    'fetchpriority' => null
  ]
];

?>

License

MIT