PHPackages                             mullema/k3-image-clip - 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. mullema/k3-image-clip

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

mullema/k3-image-clip
=====================

Visual image clip for Kirby 3

3.2.0(3y ago)363.6k5[8 issues](https://github.com/mullema/k3-image-clip/issues)MITVue

Since Apr 19Pushed 3y ago2 watchersCompare

[ Source](https://github.com/mullema/k3-image-clip)[ Packagist](https://packagist.org/packages/mullema/k3-image-clip)[ RSS](/packages/mullema-k3-image-clip/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (19)Used By (0)

Kirby 3: Image Clip
===================

[](#kirby-3-image-clip)

Visual image clipping / cropping.

[![Image Clip](https://camo.githubusercontent.com/74f78c236e3cbd463347f7c9cc85c7a7d148f2f9209a6c84ebb1b51fdb29d8a0/68747470733a2f2f7777772e6d6f656c692e636f6d2f646f776e6c6f61642f696d6167652d636c69702d322e676966)](https://camo.githubusercontent.com/74f78c236e3cbd463347f7c9cc85c7a7d148f2f9209a6c84ebb1b51fdb29d8a0/68747470733a2f2f7777772e6d6f656c692e636f6d2f646f776e6c6f61642f696d6167652d636c69702d322e676966)

Overview
--------

[](#overview)

- [Installation](#Installation)
- [Requirements](#Requirements)
- [Consider a donation](#Consider-a-donation)
- [Panel Usage](#Panel-usage)
- [Replace Files Field](#replace-files-field)
- [Frontend Usage](#Frontend-usage)
    - [Single Image](#single-image)
    - [Multiple Images](#multiple-images)
    - [File Methods](#file-methods)
    - [Responsive: srcset](#file-srcset)
- [License](#License)

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

[](#installation)

#### Download

[](#download)

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

#### Git submodule

[](#git-submodule)

```
git submodule add https://github.com/mullema/k3-image-clip.git site/plugins/k3-image-clip

```

#### Composer

[](#composer)

```
composer require mullema/k3-image-clip

```

### Requirements

[](#requirements)

- Kirby 3.6 -> use v3
- 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
-------------------

[](#consider-a-donation)

This plugin is free but if you use it in a commercial project please consider to [make a donation](https://www.paypal.me/mullema/10).

Panel Usage
-----------

[](#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](https://getkirby.com/docs/reference/panel/fields/files).

Example blueprint:

```
myimages:
  type: image-clip
  query: site.find('photography/animals').images
  layout: cards
  size: small
  clip:
    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](https://getkirby.com/docs/reference/panel/blueprints/file). You can filter the images list by template like that:

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

Replace Files Field
-------------------

[](#replace-files-field)

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

```
type: files
```

with

```
type: image-clip
```

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

Frontend Usage
--------------

[](#frontend-usage)

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

### Single Image

[](#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

[](#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

[](#file-methods)

#### `$file->clip()`

[](#file-clip)

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`

#### `$file->srcset()`

[](#file-srcset)

Use this method to generate the srcset attribute for responsive images. Read more about it's functionality in the [Kirby3 Docs](https://getkirby.com/docs/guide/templates/resize-images-on-the-fly#responsive-images)

```
myimages()->toImage()): ?>