Download the PHP package craftyhedge/craft-thumbhash without Composer

ThumbHash for Craft CMS

Automatic thumbhash placeholder generation for Craft CMS image assets.

Table of Contents

• What is ThumbHash?
• Example
• Requirements
• Installation
• Basic Usage
• Rendering
• Configuration
• Performance & Scaling
• Control Panel Features
• CLI & Maintenance
• Reference
• Notes
• Logging
• License

What is ThumbHash?

ThumbHash is a tiny visual fingerprint of an image — a ~28-byte base64 string that captures the overall color and structure. This plugin generates those hashes on the backend and ships a small client-side JS decoder that turns each hash into a PNG placeholder right in the browser.

The result: an immediate, content-aware preview while the full image loads, improving perceived performance and reducing layout jank — with virtually zero per-image cost in your HTML.

How it works

1. Backend — On upload (or via CLI), the plugin creates a small transform of the original image and encodes it to a ~28-byte base64 hash using the ThumbHash algorithm. Generation runs in a queue job so it never blocks a request.
2. Frontend — A single inline decoder script (~5 KB minified) registers a MutationObserver that automatically converts every data-thumbhash attribute into a PNG placeholder data URL as the DOM is built. It then applies that placeholder using the configured render method (bg by default, or img/picture). No extra network requests, no visible pop-in.

That's it for most sites. Drop the hash in your markup, register the script once, and placeholders appear before images even start loading.

Using the bg mode even provides LQIPs for eager loaded images! Since the placeholder is decoupled from lazy loading the full image simply overlays the placeholder once downloaded natively by the browser.

Optional: Inline PNG Data URLs

If you need placeholders without any JavaScript — for example in RSS feeds, AMP pages, or HTML emails — the plugin can also pre-decode each hash to a PNG data URL on the server and store it in the database.

• Typically ~0.8–2 KB per image (before HTTP compression), still smaller and better-looking than most blurred LQIPs.
• The backend generator automatically reads the original image dimensions and applies an exact center-crop to the decoded PNG to perfectly match the asset's aspect ratio, preventing layout shifts.
• Opt in with the generateDataUrl setting (enabled by default).
• Use thumbhashDataUrl(asset) in your templates to get the ready-made data URL.

For regular websites, the JS decoder is the recommended approach — it keeps per-image markup tiny and works great with lazy-loading libraries and infinite scroll.

Example

ThumbHash placeholders retain accurate colors and smooth gradients. They encode information to a string that is smaller than a typical LQIP URL!

Check it out - ThumbHash Example

Photo by Sanjeevan SatheesKumar on Unsplash

Requirements

• Craft CMS 5.0+
• PHP 8.2+

Installation

Basic Usage

Note: The inline script {{ thumbhashScript() }} must be included on any page where you want placeholders to render unless using the No-JS option.

The decoder script decodes each hash to a tiny PNG data URL and applies it according to the render method (bg, img, or picture; default is bg). Use data-thumbhash-render="srcset" explicitly on a <picture> when each child source should use its own hash. The script is inlined (no extra HTTP request). By default it is registered in <head> (configurable via scriptPosition), which allows the MutationObserver to start before <body> elements are parsed so placeholders appear as the DOM is built rather than after.

Your lazy loading library (lazysizes, lozad, etc.) handles swapping data-src → src when the element enters the viewport.

For <img> placeholders written directly to src, either set data-thumbhash-render="img" per element, or set renderMethod to 'img' globally in config.

Rendering

Background Image Support

Pass the hash with data-thumbhash and set data-thumbhash-render="bg" (or rely on the global default). The decoder will populate style.backgroundImage and apply the configured background placeholder styles for you. By default that is background-repeat: no-repeat, background-size: cover, and background-position: center.

A distinct benefit of the background image approach is that it decouples your LQIP from lazyloading. Eager-loaded images display the placeholder instantly, and the full image seamlessly overlays it once downloaded natively by the browser.

Use src="{{ thumbhashTransparentSvg() }}" when using background mode. This prevents empty src violations and native browser 'no image' placeholders.

Picture Element Support

The decoder also supports <picture> elements with multiple <source> children. When data-thumbhash is placed on a <picture> with data-thumbhash-render="picture", the decoder propagates that single hash to child <source data-srcset> and <img> elements so each gets its own placeholder.

The placeholder ratio is derived from the width and height attributes on each element, so you can have different aspect ratios for each breakpoint if needed. If no valid dimensions are found, the decoder falls back to the ThumbHash's native decoded dimensions (no ratio crop/resize).

Use picture mode when your sources are transforms or crops of the same asset and one representative hash is good enough.

Srcset Picture Support

When each <source> uses a different Craft asset, use data-thumbhash-render="srcset" explicitly on the parent <picture> and put each asset's own data-thumbhash on the corresponding child. The parent still handles applying placeholders to child <source data-srcset> elements and the fallback <img>, but each child is decoded from its own hash.

Like picture mode, each child placeholder is cropped/resized from that child's own width and height attributes.

What should you use?

Note: Due to the nature of ThumbHash placeholders, the accuracy the picture method provides tends to be overkill. ThumbHashes are blurry and slight differences between it and the final image are very hard to notice for most use cases. Background placeholders with cover sizing do the job very well and have the bonus of giving eager loaded images LQIPs too!

Fallback vs. Explicit Rendering

Choose one of these patterns depending on how much per-element control you need.

Approach A: Explicit per element (recommended for mixed projects)

Set data-thumbhash-render on each element (or wrapper) so your CSS can branch safely by mode.

Approach B: Config fallback (minimal markup)

Omit data-thumbhash-render and let the plugin-wide renderMethod config decide mode.

In this fallback approach, CSS cannot infer the active mode from element attributes alone. Use mode-agnostic CSS or add a global page class that mirrors your configured default mode.

No JavaScript Option

For the no JS decoding option, you can use thumbhashDataUrl() to get the decoded PNG data URL directly and set it as an inline background image:

CSS for Smooth Lazyloading Class Swaps

.img-wrapper is just an example wrapper class for your image elements, adjust as needed for your markup. This could be a picture element.

If you are mixing modes, prefer explicit data-thumbhash-render attributes and use mode-aware CSS:

Configuration

Copy the plugin config template from src/config.php to config/thumbhash.php in your Craft project, then uncomment and adjust only the options you need:

• src/config.php

Minimal example:

Folder Rules

You can scope thumbhash generation to specific folders within volumes using includeRules and ignoreRules. Both are keyed by scope: use '*' for global rules or a volume handle for volume-specific rules. Rule values support * wildcards and are matched against asset folder paths. Values without * are treated as folder prefixes (e.g. 'products' becomes 'products/*').

Ignore rules are applied after include rules. Volumes without include rules stay eligible unless a global '*' include rule is configured.

Performance & Scaling

A decoder benchmark tool is available for measuring client-side decode performance in your browser.

Transform Source

For the best server performance, it is recommended to use an external transform service like Imgix or Cloudflare Images.

If your project is set up to replace native Craft transforms with an external service, ThumbHash should use it too. You can verify the source URL used for hash generation in the ThumbHash logs.

For example, Imgix users could use the Imgixer plugin and configure it to replace the Craft transform source:

Now ThumbHash and all your CP images will use the Imgix source for transforms.

• Servd Hosting: Works great on Servd hosting. Use their plugin to replace Craft transforms with Servd's image optimization service.

Transform Concurrency

When generating thumbhashes for large batches of assets, the plugin needs to fetch many transformed images. The fetchConcurrency setting controls how many HTTP requests it will make in parallel during this prefetch step.

The default concurrency is 3, which is conservative and safe for local transforms. If you use a CDN-backed transform service that handles concurrent requests well, you can increase fetchConcurrency (e.g. 8–10) to speed up batch prefetch significantly.

The difference with 10+ concurrent fetches on 100s or 1000s of assets can be dramatic.

If you push this too high you might see some failed fetches due to rate limits or server resource constraints, so adjust according to your hosting environment and transform source capabilities.

With all this praise of external transform services, it's worth noting that the default Craft transform generation still works just fine with this plugin. It just won't be as fast for large batches of assets like when you first backfill existing assets.

If you are developing and need to clear the stored thumbhashes for whatever reason, the transforms will be reused on the next generation run, so subsequent runs will be much faster after the initial generation.

Asynchronous Generation

• ThumbHash generation is performed asynchronously in a queue job to avoid blocking the request thread.
• If autoGenerate is enabled, uploading or replacing an image asset will trigger a new hash generation job for that asset.
• When uploading large numbers of assets, Craft processes them in small batches only triggering a few hash generation jobs at any one time.

Control Panel Features

Asset Metadata

For supported image assets, the plugin also surfaces ThumbHash data in the Craft control panel:

• Asset details show a ThumbHash metadata field with the stored hash string.
• Asset details show a #PNG metadata preview when a PNG data URL is available.
• The Assets index gets a #PNG preview column by default when generateDataUrl is enabled.

Maintenance Utility

The plugin also adds a Utilities -> ThumbHash utility panel for maintenance tasks:

• Queue generation for missing or modified image assets.
• Preview stored PNG placeholders across assets.
• Clear all stored thumbhash records.

CLI & Maintenance

Backfilling Existing Assets

To generate thumbhashes for assets that existed before the plugin was installed:

Folder rules (includeRules/ignoreRules) always apply. --volume overrides the configured volumes allowlist but does not bypass folder rules.

This command queues a batch job and returns immediately with the queued job ID. Processing starts when your Craft queue runner picks up the job.

Large asset sets with server-side transforms can be slow — consider running during low-traffic periods or using an external transform service.

Clearing Stored Thumbhashes

From the Control Panel Utility:

• Open Utilities → ThumbHash
• Click Clear All
• Confirm the prompt to delete all stored thumbhash records

From CLI:

The --yes=1 flag is required as a safety guard for this destructive action.

Reference

Template Functions

JavaScript API

The decoder exposes a global API for manual use:

This API mirrors the default ThumbHash browser encoder. It does not use the plugin's server-side compressed PNG generation path.

• Scope: window.thumbhash is a browser global and only exists on pages where thumbhashScript() is included.
• Availability: it is available to any frontend JavaScript (vanilla JS, Alpine, React, Vue, etc.) after the decoder script has loaded.
• Not available in PHP or CLI contexts.

Example:

If no valid target ratio is available, toDataURL() returns the placeholder at the ThumbHash's native decoded dimensions.

Notes

• SVGs are skipped — they can't be rasterized to pixels for hashing
• Animated GIFs — only the first frame is hashed
• Imagick is preferred over GD for proper 8-bit alpha channel support
• Hashes and png urls are stored in a custom thumbhashes DB table with a foreign key cascade to the elements table

Logging

This plugin registers its own log target and writes to:

• storage/logs/thumbhash-YYYY-MM-DD.log

Notes:

• In dev mode, info/warning/error messages are logged by default.
• Set logDebug to true in config/thumbhash.php to include debug-level plugin events in dev mode.
• In non-dev mode, warning/error messages are logged.

License

The Craft License — see LICENSE.md.

The client-side decoder includes code from evanw/thumbhash (MIT License).