Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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.5 -> use v2.2.0
  • Kirby 3.3 -> use v2.1.0
  • Kirby 3.2.5 -> use v2.0.0
  • 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')

Replace Files Field

The image-clip field is able to replace a files field by changing the field type. Simply replace

type: files


type: image-clip

This works also vice versa to use the native files field instead of the image-clip field.

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()