Skip to main content
Blurry Preview Images

Blurry Preview Images

Improves your sites UX by avoiding image pop-in. Generates image hashes for displaying blurry previews when loading images on the frontend. Image hashes condense the shape of your image into around 20-50 bytes.

npm install @danielbiegler/vendure-plugin-blurry-image-lazy-loading
Latest version1.1.1
Compatibility>=3.0.0
Last publishedAug 30, 2025
Vendure Community
Vendure CommunityOpen source plugins by the Vendure community

Banner Image

Generates image hashes for displaying blurry previews when loading images on the frontend.

npm version badge

Features

  • CustomField on Asset Entities containing a hash for your frontend.
  • Automatic creation of hashes for new assets via event bus.
  • Synchronous creation of hashes for direct consumption.
  • Asynchronous creation of hashes via dedicated job queue.
  • Out of the box comes with two different hashing strategies and can be extended if need be via a custom PreviewImageHashStrategy.
  • Suite of end-to-end tests ensuring correctness.

End-To-End Tests

✓ blurry-image-lazy-loading/e2e/thumbhash.e2e-spec.ts (8 tests) ✓ blurry-image-lazy-loading/e2e/blurhash.e2e-spec.ts (8 tests) ✓ blurry-image-lazy-loading/e2e/common.e2e-spec.ts (14 tests) Test Files 3 passed (3) Tests 30 passed (30)

Example comparisons

The ThumbHash Website has an interactive online comparison generator.

size-comparison-banner.png

size-comparison-camera.png

size-comparison-lipstick.png

size-comparison-opera.png

How To: Usage

The plugin adds a couple ways to generate hashes for you to the admin api endpoint. Your admin-client needs the CreateAsset Vendure permission in order to call the following mutations. See resolver.

See api-extensions.ts for a complete overview of the graphql extensions and types.

1. Add the plugin to your Vendure Config

You can find the package over on npm and install it via:

The simplest way is relying on the defaults and just adding the plugin with a hashing strategy.

It's possible to pass in further configurations into both the plugin and the strategies, for example:

Please refer to the specific docs for how and what you can customize.

2. Generate a database migration

This plugin adds a custom field to the Asset entity called previewImageHash, which requires you to generate a database migration. See Vendure's migration documentation for further guidance.

3. Generate hashes

By default the option enqueueHashingAfterAssetCreation automatically adds hashing tasks to the dedicated job queue for newly added assets.

For existing assets you can produce hashes either synchronously or via the job queue, of which the latter is recommended for production environments, via the admin API:

4. Consume the hashes in your frontend

Now that your assets have hashes you may consume them on your frontend. How and where you consume them exactly is dependent on your setup, but in general it involves the following steps.

  1. Retrieve assets, for example:
  1. For example with the ThumbHashStrategy and its BufferEncoding set to the default "base64" you can now decode the hashes with the provided helper like so:
  1. Use the result in your frontend. There are some environment specific implementation details, so we'll use an imaginary react component here for brevity.

Practical Guides and Resources

Guides

Resources

Credits