@unlazy/vue

The Vue integration provides an UnLazyImage component for your Vue 3 application.

Installation

Install the @unlazy/vue package using your favorite package manager:

pnpm

pnpm add -D @unlazy/vue

yarn

yarn add -D @unlazy/vue

npm

npm install -D @unlazy/vue

Local Import

Import the UnLazyImage component in your Vue single file component and use it in your template:

<script setup lang="ts">
import { UnLazyImage } from '@unlazy/vue/components'
</script>

<template>
  <UnLazyImage
    blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
    auto-sizes
  />
</template>

Global Registration

If you prefer to make the UnLazyImage component globally available, you can register it in your main.ts file across your entire Vue application:

// src/main.ts
import Unlazy from '@unlazy/vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.use(Unlazy)
app.mount('#app')

UnLazyImage Component

The UnLazyImage component allows you to easily implement unlazy in your Vue application, providing a smoother image loading experience. The component supports automatic calculation of the sizes attribute with the autoSizes prop. It also enables you to specify a blurhash for the blurry placeholder image.

Props

The UnLazyImage component accepts the following props:

Prop	Type	Default	Description
src	String	-	Image source URL to be lazy-loaded.
srcSet	String	-	Image source set to be lazy-loaded.
autoSizes	Boolean	false	Whether the sizes attribute should be automatically calculated.
blurhash	String	-	A BlurHash string representing the blurry placeholder image.
thumbhash	String	-	A ThumbHash string representing the blurry placeholder image. If both are provided, thumbhash takes precedence.
placeholderSrc	String	-	Optional image source URL for a custom placeholder image. Ignored if a hash is provided.
placeholderSize	Number	32	The size of the longer edge for BlurHash decoding. Ignored for ThumbHash.
preload	Boolean	false	Whether the image should be preloaded immediately, bypassing lazy loading.
loading	String	'lazy'	Loading strategy for the image ('lazy' or 'eager').

The component also accepts all standard <img> HTML attributes via Vue's attribute inheritance.

Emitted Events

Event	Payload	Description
loaded	HTMLImageElement	Emitted when the image has been successfully loaded.
error	Event	Emitted when an error occurs during image loading.

Reactivity

The component uses Vue's watchEffect to handle reactive updates:

• Automatically tracks changes to src, srcSet, and hash props
• Re-initializes lazy loading when relevant props change
• Cleans up previous listeners before setting up new ones
• Bypasses lazy loading entirely when preload is true

Examples

BlurHash

<UnLazyImage
  width="800"
  height="600"
  blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
  src-set="image-320w.jpg 320w, image-640w.jpg 640w"
  auto-sizes
/>

ThumbHash

<UnLazyImage
  width="800"
  height="600"
  thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
  src-set="image-320w.jpg 320w, image-640w.jpg 640w"
  auto-sizes
/>

Inlined placeholder image

<UnLazyImage
  width="800"
  height="600"
  placeholder-src="data:image/svg+xml, ..."
  src-set="image-320w.jpg 320w, image-640w.jpg 640w"
  auto-sizes
/>

TIP

In each example, the sizes attribute is automatically calculated given the auto-sizes prop.

INFO

When using BlurHash, set explicit width and height attributes for optimal performance. Without these, BlurHash decoding falls back to rendered dimensions, which may cause performance delays on large images.

Preload Image

Useful if the UnLazyImage is part of e.g. a slider, and you want to preload the next image.

<template>
  <UnLazyImage
    :blurhash="blurhash"
    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
    auto-sizes
    preload
  />
</template>