Skip Navigation
ThumbHash
Docs

Advanced

Get Started

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 attribute to the element 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() ?>"
/>

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

Options

Each method also allows you to specify the ratio and blur radius as options array.

$file->thumbhash([ 'ratio' => 16/9 ]); // will return thumbhash string, cropped to 16:9
$file->thumbhashUri([ 'blur' => 2 ]); // will return placeholder, encoded in an svg with blur filter
$file->thumbhashUri([ 'ratio' => 3/2, 'blur' => 0 ]); // will return placeholder as base64-encoded png without filter, cropped to 3:2

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

tobimori.thumbhash. Default Accepts Description
cache.decode true boolean Enable decoding cache
cache.encode true boolean Enable encoding cache
sampleMaxSize 100 number Max width or height for smaller image that gets encoded (watch out for memory)
blurRadius 1 number Default radius of the SVG blur filter applied 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.blurhash' => [
        'sampleMaxSize' => 200,
        'componentsTarget' => 12,
        'decodeTarget' => 100,
    ],
];