Usage

Client-side decoding

$file->thumbhash()

Encodes the image with ThumbHash and returns ThumbHash as a string

The default implementation of ThumbHash expects the string to be decoded on the client-side.

This provides the most benefits, most notably including better color representation and smaller payload size, but requires the initial execution of such a library on the client-side, and thus is better used with a headless site or heavily makes use of client-side infinite scrolling/loading.

With an lazy-loading library like unlazy you can implement lazy-loading with client-side decoding easily by providing the thumbhash as attribute.

<img
  data-thumbhash="<?= $image->thumbhash() ?>"
  data-src="<?= $image->url() ?>" // Original src attribute will be placed by unlazy
  loading="lazy"
  alt="<?= $image->alt() ?>"
/>

Server-side decoding

$file->thumbhashUri()

Encodes the image with ThumbHash, then decodes & rasterizes it. Finally returns it as a data URI which can be used without any client-side library.

In addition to simply outputting the ThumbHash string for usage on the client-side, this plugin also provides a server-side decoding option that allows you to output a base64-encoded image string, which can be used as a placeholder image without any client-side libraries, similar to Kirby Blurry Placeholder.

This is especially useful when you only have a few images on your site or don't want to go through the hassle of using a client-side library for outputting placeholders. Using this approach, you'll still get better color representation of the ThumbHash algorithm than with regularly downsizing an image, but image previews will still be about ~1kB large.

<img src="<?= $image->blurhashUri() ?>" />