Vue Blurhash Components

0.1.4 · maintenance · verified Sun Apr 19

The `vue-blurhash` package provides a set of Vue 2 components designed to implement Blurhash image placeholders. It allows developers to display a compact, low-resolution representation of an image while the full-resolution image loads, enhancing the perceived performance and user experience of web applications. The library offers two primary components: `<blur-hash-image>` for a complete image loading solution including an optional fade transition, and `<blur-hash-canvas>` for generating only the Blurhash placeholder on a canvas, enabling custom image loading logic. As of its current stable version 0.1.4, it specifically targets Vue.js 2.0+ environments. Its release cadence appears infrequent, typical for a specialized utility library tied to an older major framework version. A key differentiator is its straightforward integration as a Vue plugin, simplifying the process of adding Blurhash functionality without extensive manual implementation of the `blurhash` algorithm itself.

Common errors

```
[Vue warn]: Unknown custom element: <blur-hash-image> - did you register the component correctly?
```
cause The `vue-blurhash` plugin has not been registered with the Vue instance using `Vue.use()`.

fix Add `Vue.use(VueBlurHash)` to your application's entry point before creating your main Vue instance.
```
TypeError: Cannot read properties of undefined (reading 'decode') or TypeError: blurhash__WEBPACK_IMPORTED_MODULE_2__.decode is not a function
```
cause The `blurhash` peer dependency is missing from the project, preventing the library from decoding the hash.

fix Install the `blurhash` package: `npm install blurhash` or `yarn add blurhash`.
```
The placeholder image disappears abruptly without a fade-in effect when the actual image loads.
```
cause The required CSS for the fade transition (`vue-blurhash/dist/vue-blurhash.css`) has not been imported into your application.

fix Add `import 'vue-blurhash/dist/vue-blurhash.css'` to your application's main JavaScript file or a suitable style entry point.

Warnings

breaking This library is explicitly designed for Vue 2.x applications and is not compatible with Vue 3. Attempting to use it in a Vue 3 project will result in runtime errors due to fundamental API changes between Vue major versions.
Fix: For Vue 3, consider using a different Blurhash library or implementing the functionality manually tailored for Vue 3's composition API or component structure.
gotcha The `blurhash` package is listed as a peer dependency, meaning it must be manually installed alongside `vue-blurhash`. The component functionality relies directly on this core `blurhash` library at runtime.
Fix: Ensure you install the `blurhash` package in your project using `npm install blurhash` or `yarn add blurhash`.
gotcha The fade-in transition effect for the loaded image, demonstrated in the `<blur-hash-image>` component, requires the explicit import of the provided CSS file: `import 'vue-blurhash/dist/vue-blurhash.css'`. Without this import, the placeholder will simply disappear when the image loads, without a smooth transition.
Fix: Add `import 'vue-blurhash/dist/vue-blurhash.css'` to your application's entry point or a relevant component file where the styles are needed.

Install

npm install vue-blurhash npm
yarn add vue-blurhash yarn
pnpm add vue-blurhash pnpm

Imports

VueBlurHash
wrong:
```
const VueBlurHash = require('vue-blurhash')
```
correct:
```
import VueBlurHash from 'vue-blurhash'
```
Used for plugin registration with `Vue.use()`. The CommonJS `require` syntax is typically not used for frontend Vue component libraries.
BlurHashCanvas
wrong:
```
import BlurHashCanvas from 'vue-blurhash'
```
correct:
```
import { BlurHashCanvas } from 'vue-blurhash'
```
This is a named export for the canvas-only component. Do not use a default import.
CSS Stylesheet
```
import 'vue-blurhash/dist/vue-blurhash.css'
```
Required for the default fade transition effect when the full image loads in `<blur-hash-image>`.

Quickstart

This quickstart demonstrates how to register `vue-blurhash` as a Vue 2 plugin, import its necessary CSS, and then utilize both the `<blur-hash-image>` component for a complete image loading experience and the `<blur-hash-canvas>` for just displaying the blurhash placeholder.

import Vue from 'vue';
import VueBlurHash from 'vue-blurhash';
import 'vue-blurhash/dist/vue-blurhash.css'; // For fade transition effect

Vue.use(VueBlurHash);

new Vue({
  el: '#app',
  template: `
    <div id="app">
      <h1>Image with Blurhash Placeholder</h1>
      <blur-hash-image
        width="400"
        height="300"
        hash="LdHfL}oJR$WBKnfi%3ofT0kCM{ay"
        src="https://images.unsplash.com/photo-1545910684-8e7c081be9b0?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1867&q=80"
        alt="green lawn grass during daytime"
        transitionDuration="800"
      />
      <h2>Canvas-only Placeholder</h2>
      <blur-hash-canvas
        hash="LdHfL}oJR$WBKnfi%3ofT0kCM{ay"
        width="200"
        height="150"
        punch="1.2"
      />
    </div>
  `,
});

view raw JSON →