Advanced

Cropped images

Kirby doesn’t support file methods on cropped images, so you’ll have to use the original image, and pass the ratio as a parameter to get the correct ThumbHash.

<?php $cropped = $original->crop(500, 400) ?>
<img
  src="<?= $original->thumbhashUri(5/4) ?>"
  data-src="<?= $cropped->url() ?>"
  data-lazyload
  alt="<?= $original->alt() ?>"
/>

All methods support the ratio parameter:

• $file->thumbhash($ratio)
• $file->thumbhashUri($ratio, $blurRadius)
• $file->averageColor($format, $ratio)
• $file->averageColorRgba($ratio)

Working with static assets (using asset() helper)

All methods are available as asset methods since Kirby 3.9.2.

asset('assets/image.jpg')->thumbhash();
asset('assets/image.jpg')->thumbhashUri();

Read more about the asset() helper here.

Aliases

$file->th(); // thumbhash()
$file->thUri(); // thumbhashUri()

Parameters

All methods support clean parameter syntax for better readability:

// Encoding with custom ratio
$file->thumbhash(16/9); // cropped to 16:9

// Server-side placeholder with custom blur
$file->thumbhashUri(null, 2); // blur radius of 2
$file->thumbhashUri(3/2, 0); // cropped to 3:2, no blur (raw PNG)

// Average colors with custom ratio
$file->averageColor('rgb', 16/9); // modern CSS format, 16:9 ratio
$file->averageColorRgba(4/3); // RGBA array, 4:3 ratio

Named parameters are also supported for clarity:

$file->thumbhashUri(ratio: 16/9, blurRadius: 2);
$file->averageColor(format: 'rgba', ratio: 1.5);

Legacy array syntax (deprecated but still supported):

$file->thumbhash(['ratio' => 16/9]);
$file->thumbhashUri(['ratio' => 3/2, 'blurRadius' => 0]);

Clear cache

The encoding cache is automatically cleared when an image gets replaced or updated, however you can also clear the cache manually with the clearCache static method:

<?php

use tobimori\ThumbHash;

ThumbHash::clearCache($file);

This might be helpful when you use third party plugins to edit your images, and they do not trigger Kirby’s internal file update hooks but instead have their own.

Options

| Option | Default | Description | | ————— | —–– | ———————————————————————————————–– | | cache.decode | true | Enable decoding cache | | cache.encode | true | Enable encoding cache | | engine | 'gd' | Image processing driver: 'gd' or 'imagick' (Imagick offers better performance and quality) | | sampleMaxSize | 100 | Max width or height for sample image that gets encoded (affects memory usage and quality) | | blurRadius | 1 | Default radius of the SVG blur filter applied to decoded image, set to 0 for raw base64 PNG |

Options allow you to fine tune the behaviour of the plugin. You can set them in your config.php file:

return [
    'tobimori.thumbhash' => [
        'engine' => 'imagick', // use Imagick for better performance (requires ext-imagick)
        'sampleMaxSize' => 100,
        'blurRadius' => 1,
    ],
];

Image Processing Drivers

The plugin supports two image processing drivers:

• GD (default): Uses PHP’s built-in GD extension. Always available, good performance.
• Imagick: Uses the Imagick extension. Offers better performance and quality, especially for larger images.

To use Imagick, install the PHP extension and set the engine option:

# Install Imagick extension (varies by system)
pecl install imagick

// config.php
return [
    'tobimori.thumbhash.engine' => 'imagick',
];

Error Handling

When sample thumb generation fails, the plugin returns null silently in production. If you have Kirby’s debug mode enabled, it will throw an exception with a detailed error message instead. The failed thumbnail is automatically deleted to allow retry on next request.