Vue Lazy Image Loading

Vue progressive image and background loading plugin.

Installation

npm install vue-lazy-image-loading

Usage

import Vue from 'vue'
import VueLazyImageLoading from 'vue-lazy-image-loading'

Vue.use(VueLazyImageLoading)

Lazy image

Instead of using the normal img tag to load images

<img src="https://unsplash.it/1920/1080?image=10" />

use the lazy-img component already globally available after the plugin installation

<lazy-img src="https://unsplash.it/1920/1080?image=10" />

Lazy background

It is also possible to apply lazy images as backgrounds and it will have the same props as the lazy-img component

<lazy-background src="https://unsplash.it/1920/1080?image=10" />

Global properties

There is all properties you can use for both lazy-img and lazy-background components.

Placeholder

To be able to immediately show some feedback to the user, it is possible to pass a placeholder image, which could be also 1% the size of the main image: it will be blurred so you can go crazy with optimizations here.

In this example I actually use the same image, but you have the idea here

<lazy-img
  src="https://unsplash.it/1920/1080?image=10"
  placeholder="https://unsplash.it/1920/1080?image=10"
/>

Blur

It is possible to adjust the level of blur applied to the placeholder image

<lazy-img
  src="https://unsplash.it/1920/1080?image=10"
  placeholder="https://unsplash.it/1920/1080?image=10"
  :blur="30"
/>

Ratio

It is possible to remove the padding that adds the aspect ratio to the container.

<lazy-img
  src="https://unsplash.it/1920/1080?image=10"
  no-ratio
/>

It is also possible to manually specify the image aspact ratio when you know it. It allows the placeholder to be displayed in the correct aspect ratio. The ratio is calculated as height / width.

<lazy-img
  src="https://unsplash.it/1920/1080?image=10"
  aspect-ratio="1.5"
/>

`lazy-background` properties

There is all properties you can use for the lazy-background component only.

Background position

Allows you to set the value of the background-position CSS property.

The default value is 0% 0%.

<lazy-background
  src="https://unsplash.it/1920/1080?image=10"
  position="center"
/>

Background size

Allows you to set the value of the background-size CSS property.

The default value is cover.

<lazy-background
  src="https://unsplash.it/1920/1080?image=10"
  size="contain"
/>

Background repeat

Allows you to set the value of the background-repeat CSS property.

The default value is no-repeat.

<lazy-background
  src="https://unsplash.it/1920/1080?image=10"
  repeat="repeat-x"
/>

The slot

The lazy-background has a "content" slot, which can hold content that needs to be rendered over the background image and also can hold a preloader. This slot has one property called "visible" that tells you when, for example, a preloader needs to be visible or not.

<lazy-background src="https://unsplash.it/1920/1080?image=10">
  <div slot="content" slot-scope="{ visible }">
    <p>I am some content to display over the image</p>
    <div v-show="visible">I am the preloader</div>
  </div>
</lazy-background>

Image fallback

In case of a loading error of the main image, it is possible to add a fallback image which can display an error image or just another image.

<lazy-img
  src="https://this_url_should_cause_an_error"
  fallback="https://unsplash.it/1920/1080?image=10"
/>

Vue Loader - Asset URL Handling

If you're using Vue Loader, it's Asset URL transforms will not work with our lazy-img and lazy-background elements by default.

By default the following tag/attribute combinations are transformed, and can be configured using the transformAssetUrls option:

{
  video: ['src', 'poster'],
  source: 'src',
  img: 'src',
  image: 'xlink:href'
}

All you have to is to add our lazy-img and lazy-background tags to the transformAssetUrls object:

{
  video: ['src', 'poster'],
  source: 'src',
  img: 'src',
  image: 'xlink:href',
  'lazy-img': 'src',
  'lazy-background': 'src'
}

Now, Vue Loader's Asset URL transforms will work with our elements too.

Events

Each component emits an event whenever an image is loaded.

Because we usually load two images, a main image and a placeholder, two events are dispatched onLoad and onLoadPlaceholder

in your js file

export default {
  methods: {
    onLoad () {
      // main image is loaded
    },
    onLoadPlaceholder () {
      // placeholder image is loaded
    },
    onError (error) {
      // main image error
    },
    onErrorPlaceholder (error) {
      // placeholder image error
    }
  }
}

in the html just add the events you need to listen to

<lazy-img
  @onLoad="onLoad"
  @onLoadPlaceholder="onLoadPlaceholder"
  @onError="onError"
  @onErrorPlaceholder="onErrorPlaceholder"
  src="https://unsplash.it/1920/1080?image=10"
  placeholder="https://unsplash.it/1920/1080?image=10"
/>

Options

During the installation process it is possible to pass some default global options

Cached images

type: Boolean
default: true

Cached images are checked by default. This check kills the animation if the image was already loaded once. If you would like to show the animation every time, even when is not needed, you can simply use the plugin options like so:

Vue.use(VueLazyImageLoading, {
  cache: false
})

placeholder

type: String
required: false

Vue.use(VueLazyImageLoading, {
  placeholder: 'https://unsplash.it/1920/1080?image=20'
})

blur

type: Number
required: false
default: 5

Vue.use(VueLazyImageLoading, {
  blur: 30
})

delay

type: Number
default: 0

This options is for debug only. It lets you have an easy look at the placeholder before the main image is fully loaded.

Vue.use(VueLazyImageLoading, {
  delay: 2000 // 2 seconds before the image is displayed
})

position

type: String
default: '0% 0%'

Allows you to set the value of the background-position CSS property. Will only work lazy-background component.

Vue.use(VueLazyImageLoading, {
  position: 'center'
})

size

type: String
default: 'cover'

Allows you to set the value of the background-size CSS property. Will only work lazy-background component.

Vue.use(VueLazyImageLoading, {
  size: 'contain'
})

repeat

type: String
default: 'no-repeat'

Allows you to set the value of the background-repeat CSS property. Will only work lazy-background component.

Vue.use(VueLazyImageLoading, {
  repeat: 'repeat-x'
})

Global options like placeholder and blur will be applied only to components that don't specify their own options

subotkevic/vue-lazy-image-loading