PHPackages dodecastudio/craft-blurhash - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. dodecastudio/craft-blurhash ActiveCraft-plugin[Image & Media](/categories/media) dodecastudio/craft-blurhash =========================== Render a BlurHash from a given image. 3.0.5(7mo ago)1214.9k↑37.5%1[1 PRs](https://github.com/dodecastudio/craft-blurhash/pulls)2proprietaryPHPPHP >=7.4CI failing Since Aug 3Pushed 7mo ago1 watchersCompare [ Source](https://github.com/dodecastudio/craft-blurhash)[ Packagist](https://packagist.org/packages/dodecastudio/craft-blurhash)[ RSS](/packages/dodecastudio-craft-blurhash/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (3)Versions (30)Used By (2) BlurHash plugin for Craft CMS ============================= [](#blurhash-plugin-for-craft-cms) [![Buy us a tree](https://camo.githubusercontent.com/130148911f548b001b2ac68a32c0a06559977ca60ada3bf480c72ae4ea093175/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54726565776172652d2546302539462538432542332d6c69676874677265656e)](https://plant.treeware.earth/dodecastudio/craft-blurhash) [![](src/icon.svg)](src/icon.svg) **Render a BlurHash from a given asset in Craft CMS.** A [BlurHash](https://blurha.sh/) 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](https://github.com/kornrunner/php-blurhash). Requirements ------------ [](#requirements) - Craft CMS 3.X, 4.X or 5.X - PHP 7.4+ - GD / ImageMagick (*as required by Craft CMS*) Installation ------------ [](#installation) Install the plugin as follows: 1. Open your terminal and go to your Craft project: ``` cd /path/to/project ``` 2. Then tell Composer to load the plugin: ``` composer require dodecastudio/craft-blurhash ``` 3. In the Control Panel, go to Settings β†’ Plugins and click the β€œInstall” button for BlurHash. BlurHash Overview ----------------- [](#blurhash-overview) The BlurHash plugin will generate a BlurHash image from a craft asset. Here's an example of what you can expect: ### Input: [](#input) [![](resources/img/example-01-photo.jpg)](resources/img/example-01-photo.jpg) ### Result: [](#result) [![](resources/img/example-01-blurhash.jpg)](resources/img/example-01-blurhash.jpg) Using BlurHash -------------- [](#using-blurhash) ### Common use [](#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: ``` ``` 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](https://web.dev/cls/). One way to achieve this is to use the [CSS `aspect-ratio` property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio), as used in the example above. ### Other features [](#other-features) #### Generating a blurhash string [](#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 [](#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: ``` ``` 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 [](#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](https://docs.craftcms.com/api/v3/craft-fields-data-colordata.html#public-properties). ``` {{ 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 [](#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 [](#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 [](#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 [](#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 [](#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 -------- [](#settings) Default settings can be overridden. Please see the `blurhash-config.php` file for details. Copy to `/config/blur-hash.php` to use. Licence 🌳 --------- [](#licence-) This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/dodecastudio/craft-blurhash/). And why not? By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats. ### Thanks! πŸ™Œ [](#thanks-) Shout-out to [@olsp](https://github.com/olsp) for [buying 100 trees](https://ecologi.com/treeware?tileId=623c81be1644e1fb9a93ad35) and [@mokopan](https://github.com/mokopan) for [buying 25 trees](https://ecologi.com/treeware?tileId=625e603f776930bd0b4f973a). If you've purchased trees through Ecologi, as part of the Treeware license, please let us know for a shout-out. ### Health Score 47 β€” FairBetter than 93% of packages Maintenance68 Regular maintenance activity Popularity32 Limited adoption so far Community12 Small or concentrated contributor base Maturity61 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~61 days Recently: every ~89 days Total 26 Last Release 218d ago Major Versions 1.2.1 β†’ 2.0.0-beta.12022-03-10 1.2.2 β†’ 2.0.0-beta.22022-03-23 1.2.4 β†’ 2.0.0-beta.32022-04-19 1.2.5 β†’ 2.0.22022-06-16 2.0.5 β†’ 3.0.02024-04-22 ### Community Maintainers ![](https://www.gravatar.com/avatar/d8c4bf8ffa7d145ab97391463d478d99b9ddd3a948841315be947be89c43f2be?d=identicon)[tomkiss](/maintainers/tomkiss) --- Top Contributors [![tomkiss](https://avatars.githubusercontent.com/u/183310?v=4)](https://github.com/tomkiss "tomkiss (69 commits)") --- Tags cmsCraftcraftcmscraft-pluginblurhash ### Embed Badge ![Health badge](/badges/dodecastudio-craft-blurhash/health.svg) ``` [![Health](https://phpackages.com/badges/dodecastudio-craft-blurhash/health.svg)](https://phpackages.com/packages/dodecastudio-craft-blurhash) ``` ### Alternatives [spacecatninja/imager-x Ninja powered image transforms. 29390.0k23](/packages/spacecatninja-imager-x)[doublesecretagency/craft-googlemaps Maps in minutes. Powered by the Google Maps API. 1267.9k](/packages/doublesecretagency-craft-googlemaps)[bymayo/pdf-transform Transform a PDF page to an image (JPEG, PNG) 1211.6k](/packages/bymayo-pdf-transform)[nystudio107/craft-youtubeliveembed This plugin allows you to embed a YouTube live stream and/or live chat on your webpage 163.7k](/packages/nystudio107-craft-youtubeliveembed) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)