Image thumbnails

With Kirby's Thumbnail API, thumbs are generated asynchronously. This makes thumb creation feel a lot faster and creates less memory issues, which could easily become an issue with many images or when creating many different images sizes to serve responsive images.

A new set of plugin extensions can be used to hook into the thumbnail API or the thumbnail URLs, see core components.

The thumb() method

With the thumb method, you can perform multiple image manipulations at once: resizing, cropping, changing the image format, converting to grayscale, and blurring. If you wanted to do everything at once, the code would look like this:

<img src="<?= $image->thumb(
    [
        'width'     => 300,
        'height'    => 300,
        'crop'      => 'center',
        'format'    => 'webp',
        'grayscale' => true,
        'blur'      => 300,
                'sharpen'   => 50,
        'quality'   => 70,
    ]
)->url() ?>" alt="">

In the Reference: $file->thumb()

Shortcut methods

Most of the time, you don't want to use all options though. On top, the thumb method is quite verbose. Luckily, Kirby comes with a set of shortcuts methods: resize(), crop(), grayscale(), and blur(). Additionally, you can define default settings in your config file. But one step after the other.

Here are some examples for using the shortcut methods, more details with all options in the Reference:

Resizing images

$image->resize(300);
$image->resize(300, 200);

In the Reference: $file->resize()

Cropping images

$image->crop(100);
$image->crop(100, 200);

Kirby will automatically use a focus point set for the image when set, otherwise use the default thumb settings.

In the Reference: $file->crop()

Blur

The blur method applies a blur filter to an image. You can modify the intensity of the blur effect by passing an integer. The default value is 10.

$image->blur();
$image->blur(30);

In the Reference: $file->blur()

Grayscale

The grayscale method converts an image to grayscale.

$image->grayscale();

In the Reference: $file->grayscale()

Configuring your thumbnails

Options for thumbnails are set with the thumbs key in Kirby's configuration:

return [
  'thumbs' => [
    'driver'    => 'im',
    'quality'   => 90,
    'bin'       => '/usr/local/bin/convert',
    'interlace' => true,
    'format'    => 'webp',
  ]
];

In the Reference: All thumbs options

Presets

You can define option presets for thumbs in your config.php:

return [
    'thumbs' => [
        'presets' => [
            'default' => ['width' => 1024, 'quality' => 80],
            'blurred' => ['blur' => true]
        ]
    ]
];

Then you can use these presets e.g. in your templates:

$file->thumb(); // for default preset
$file->thumb('blurred');

Responsive images

You can use Kirby's $image->srcset() method to easily create the srcset attribute for responsive images. Learn more ›

<img srcset="<?= $image->srcset([300, 800, 1024]) ?>">

Check out our cookbook recipe Responsive images to learn more.

Image formats

You can use the format option to convert an existing JPEG, GIF or PNG into a WebP or AVIF file with the thumb() method.

<?= $image->thumb(['width' => 200, 'format' => 'webp']) ?>
<?= $image->thumb(['width' => 200, 'format' => 'avif']) ?>

The format option can also be used in srcset definitions.

$image->srcset([
  '400w'  => ['width' => 400, 'format' => 'webp'],
  '800w'  => ['width' => 800, 'format' => 'webp'],
  '1200w' => ['width' => 1200, 'format' => 'webp']
])

Responsive images

With Kirby's thumb engine, you can resize, crop and otherwise manipulate images. Here are the links to relevant resources:

• Responsive images
• Custom thumb components

Thumbnail storage

In a default setup, thumbnails are stored in the /media folder.

They are placed in subfolders named based on a combination of the file's modification timestamp and the hash generated by $kirby->contentToken().

By default, this depends on the full file system path of the file, so it will likely differ between your local and remote setup. For example, if you want to pre-render thumbnails locally and upload them to your remote server, you will need to set the content.salt option on both instances so that the hash is the same and thumbnails aren't re-generated.