README

Render a BlurHash from a given asset in Craft CMS.

A BlurHash is a compact representation of a placeholder for an image. A blurred version of an image, useful for displaying whilst the full resolution image is loading.

This plugin uses kornrunner's PHP implementation of BlurHash, php-blurhash.

Requirements

Craft CMS 3.X, 4.X or 5.X
PHP 7.4+
GD / ImageMagick (as required by Craft CMS)

Installation

Install the plugin as follows:

Open your terminal and go to your Craft project:
```
cd /path/to/project
```

Then tell Composer to load the plugin:

composer require dodecastudio/craft-blurhash

In the Control Panel, go to Settings → Plugins and click the “Install” button for BlurHash.

BlurHash Overview

The BlurHash plugin will generate a BlurHash image from a craft asset. Here's an example of what you can expect:

Input:

Result:

Using BlurHash

Common use

To use the plugin, first grab an asset from Craft, perhaps something like this:

{% set testAsset = craft.assets().id(101).one() %}

You can then pass your asset to the plugin's blurhash function, which will return a blurhash image as a data-url, perfect for using in an img element like so:

<img src="{{ blurhash(testAsset) }}" width="{{testAsset.width}}" height="{{testAsset.height}}" style="aspect-ratio: {{testAsset.width}} / {{testAsset.height}};" />

Note: Due to the compact dimensions of the blurhash image, its aspect ratio may differ fractionally from the source material. Ensure any image markup correctly renders the aspect ratio based on the source markup if you are trying to prevent CLS. One way to achieve this is to use the CSS aspect-ratio property, as used in the example above.

Other features

Generating a blurhash string

If you just want to generate just a blurhash string from a given asset, you can use the blurhash filter like this:

{{ testAsset|blurhash }}

Which will return something like this:

f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay

You might want to store this in some way, for use later.

Generating a blurhash image from a blurhash string

If you already have a blurhash string and want to generate an image from it, you can use the blurhashToUri function like this:

<img src="{{ blurhashToUri('f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay') }}" width="256" height="256" alt="Blurhash image" />

Note that blurhash strings do not have any data encoded about the size or scale of the image. You may need additional information in order to display the correct aspect ratio.

Returning average color for an image

BlurHash strings contain the average color for the image. You can decode this value from a BlurHash string and return it as a Craft ColorData object.

{{ averageColor('f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay') }}
{{ averageColor('f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay').getRgb() }}

...or directly from an asset:

{{ testAsset|averageColor }}
{{ averageColor(testAsset) }}
{{ averageColor(testAsset).getRgb() }}

Returning memory info

Images need to be loaded in to memory in order to be read, and a blurhash generated. This helper function will tell you approximately how much memory (in bytes) will be needed for a given image.

{{ testAsset|memoryInfo }}

GraphQL Support

As of v1.1.0 it's possible to use the plugin via Graph QL. The same functionality that's available with the Twig functions, is now available through Graph QL directives.

Returning a blurhash data URI from an asset field

An asset field can be returned as a data uri to a blurhash image using the @assetToBlurHash directive. It can also be used to return a blurhash string by setting the asUri argument to false.

{
  entries(section: "news") {
    title
    ... on news_article_Entry {
      asset {
        blurhashString: url @assetToBlurHash(asUri: false)
        blurhashUri: url @assetToBlurHash
      }
    }
  }
}

This will return some JSON which looks a bit something like this:

{
  "data": {
    "entries": [
      {
        "title": "An important news item",
        "asset": [
          {
            "blurhashString": "f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay",
            "blurhashUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAAB..."
          }
        ]
      }
    ]
  }
}

Rendering a blurhash image from a plaintext blurhash string

If you have a blurhash string saved in a Craft, you can render it to a data URI using the @blurhashToUri directive. In this example, there is a plaintext field called blurhashStringField stored in our news article entry.

{
  entries(section: "news") {
    title
    blurhashStringField
    blurhashUri: blurhashStringField @blurhashToUri
  }
}

And that will then give us some JSON that looks a bit like this:

{
  "data": {
    "entries": [
      {
        "title": "An important news item",
        "blurhashStringField": "f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay",
        "blurhashUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAAB..."
      }
    ]
  }
}

Getting an average color for an image

If you want to return the average color for an image saved in Craft, you can use the @averageColor directive. This returns a hex color value as a string.

{
  entries(section: "news") {
    title
    ... on news_article_Entry {
      blurhashStringField @averageColor
      asset {
        averageColor: url @averageColor
      }
    }
  }
}

Which will return you some JSON like this:

{
  "data": {
    "entries": [
      {
        "title": "An important news item",
        "blurhashStringField": "#a3a696",
        "asset": [
          {
            "averageColor": "#817c82"
          }
        ]
      }
    ]
  }
}

Settings

Default settings can be overridden. Please see the blurhash-config.php file for details. Copy to /config/blur-hash.php to use.

Licence 🌳

This package is Treeware. If you use it in production, then we ask that you buy the world a tree.
And why not? By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Thanks! 🙌

Shout-out to @olsp for buying 100 trees and @mokopan for buying 25 trees.

If you've purchased trees through Ecologi, as part of the Treeware license, please let us know for a shout-out.

dodecastudio / craft-blurhash

Maintainers

Details