Skip to content
Visually crop images with a handy image editor directly inside the panel
Branch: master
Clone or download
Latest commit a1b4b6a May 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets initial Apr 19, 2019
classes Added srcset May 18, 2019
components Reset Darkroom types after use. flokosiol/kirby-focus#42 May 4, 2019
fieldMethods last Apr 19, 2019
fields panelthumbs can now be defined in config.php or plugins/index.php Apr 22, 2019
src show loading spinner on resize May 18, 2019
.gitignore ignore package-lock.json Apr 19, 2019 readme Apr 19, 2019 reorganised reame May 18, 2019
bili.config.js initial Apr 19, 2019
composer.json initial Apr 19, 2019
index.css preload spinner Apr 22, 2019
index.js new build May 18, 2019
index.php panel thumb size as option Apr 20, 2019
package.json initial Apr 19, 2019

Kirby 3: Image Clip

Visual image clipping / cropping.

Image Clip




Download and copy this repository to /site/plugins/k3-image-clip

Git submodule

git submodule add site/plugins/k3-image-clip


composer require mullema/k3-image-clip


  • Kirby 3.x
  • GD Library or ImageMagick

Consider a donation

This plugin is free but if you use it in a commercial project please consider to make a donation.

Panel Usage

This plugin comes with a image-clip field. It is based on the files field and supports all it's options. Read more about the files field in the Kirby3 Docs.

Example blueprint:

  type: image-clip
  query: site.find('photography/animals').images
  layout: cards
  size: small
    minwidth: 400
    minheight: 300
    maxwidth: 800
    maxheight: 600
    ratio: fixed
  • All values are in Pixels.
  • minwidth, minheight, maxwidth, maxheight limit the clip/crop select area.
  • None of the clip options are required, but in most cases it is recommended to define minwidth and minheight.
  • Often it makes more sense to resize the resulting image than defining maxwidth and maxheight.
  • ratio: fixed locks the ratio
    • if minwidth and minheight are defined,
    • or maxwidth and maxheight are defined,
    • or all of the above.

The field does basic checks of image size and type but counts mainly on you defining e.g, accepted mime types or image sizes in a File Blueprint. You can filter the images list by template like that:

query: site.find('photography').children.images.filterBy('template', 'cover')

Panel thumb size

In kirbys config.php you can adjust the maximal thumbnail sizes that are displayed in the image-clip field. Default is 400px width or 400px height for cards and 100px width or 100px height for lists.

If your cards get bigger you might want to adjust the numbers to 800x800px.

Note: This is only about thumbnail quality in the panel. You don't need to match the clip area numbers.

    'options' => [
        'panelthumbs' => [
            'cards' => [
                'width'  => 400,
                'height' => 400
            'list' => [
                'width'  => 100,
                'height' => 100

Frontend Usage

How to fetch the images defined in a image-clip field. Read about the clip() method a bit further down.

Single Image

if ($image = $page->myimages()->toImage()) {
    echo $image->clip(500);
  • Important: toFile does not work, use toImage() instead.
  • toImage() returns a File Object with all it's functions.

Multiple Images

foreach($page->myimages()->toImages() as $image) {
    echo $image->clip(500);
  • Important: toFiles does not work, use toImages() instead.
  • toImages() returns a Files Collection with all it's functions.

File Methods


Clip and resize. Generates a Thumbnail of the clip area.

Adapter for $file->thumb(). Returns a FileVersion|File Object.

if ($image = $page->myimages()->toImage()) {
    echo $image->clip(500);
$file->clip(200, 300);   // bestfit
$file->clip(200);        // width 200px
$file->clip(null, 300);  // height 300px
$file->clip();           // clip area without resizing
  • Used in combination with the image-clip Field, invokes automatically field clip data.
  • Arguments: clip(width, height)
    • if width and height are both defined, the image will be resized with bestfit


Use this method to generate the srcset attribute for responsive images. Read more about it's functionality in the Kirby3 Docs

<?php if ($image = $page->myimages()->toImage()): ?>
    <img srcset="<?= $image->srcset([300, 800, 1024]) ?>">
<?php endif; ?>


The thumb method accepts now the option clip and can be used with any resizable image.

    'width' => 400,
    'clip' => [
       'width' => 500,
       'height' => 200,
       'top' => 10,
       'left' => 200
  • Clips/crops a square of 500x200px, 10px from top and 200px from the left end of the original image.
  • Resizes the resulting image to 400px width.
  • If clip and crop are used at the same time, crop will be ignored.

Read more about the thumb method in the Kirby3 Docs


Returns the clip data.

Can be useful e.g with the $file->thumb() method.

if ($image = $page->myimages()->toImage()) {
    echo $image->thumb([
       'width' => 1200,
       'grayscale' => true,
       'clip' => $image->getClip()




You can’t perform that action at this time.