vue-li-image

A Vue.js component to lazy load an image automatically when it enters the viewport using the Intersection Observer API.

This is an opinionated upgrade of the original Vue Lazy Image loading library v-lazy-image including certain fixes already submitted as pull requests on the original library, which were never merged. Kudos to Alex Jover for the original idea!

Usage

npm install vue-li-image

Warning: You'll need to install the w3c Intersection Observer polyfill in case you're targeting a browser which doesn't support it.

You can register the component globally so it's available in all your apps:

import Vue from "vue";
import { VueLiPlugin } from "vue-li-image";

Vue.use(VueLiPlugin);

Or use it locally in any of your components:

import VueLi from "vue-li-image";

export default {
  components: {
    VueLi
  }
};

You must pass an src property with the link of the image:

<template>
  <vue-li src="http://lorempixel.com/400/200/" />
</template>

That image will be loaded as soon as the image enters the viewport.

Progressive Loading

You can use the src-placeholder property to define an image that is shown until the src image is loaded.

When the src image is loaded, a vue-li-loaded class is added, so you can use it to perform animations. For example, a blur effect:

<template>
  <vue-li
    src="https://cdn-images-1.medium.com/max/1600/1*xjGrvQSXvj72W4zD6IWzfg.jpeg"
    src-placeholder="https://cdn-images-1.medium.com/max/80/1*xjGrvQSXvj72W4zD6IWzfg.jpeg"
  />
</template>

<style scoped>
.vue-li {
  filter: blur(10px);
  transition: filter 0.7s;
}
.vue-li {
  filter: blur(0);
}
</style>

In case you are using Webpack bundler for images too (just like Vue-cli):

<vue-li
  src="https://cdn-images-1.medium.com/max/1600/1*xjGrvQSXvj72W4zD6IWzfg.jpeg"
  :src-placeholder="require('../assets/img.jpg')"
/>

You could listen to the intersect and load events for more complex animations and state handling:

<template>
  <vue-li
    src="https://cdn-images-1.medium.com/max/1600/1*xjGrvQSXvj72W4zD6IWzfg.jpeg"
    src-placeholder="https://cdn-images-1.medium.com/max/80/1*xjGrvQSXvj72W4zD6IWzfg.jpeg"
    @intersect="..."
    @load="..."
  />
</template>

@jmperezperez has written about the progressive loading technique on his blog, in case you want a deeper explanation.

Responsive Images

Using the srcset property you can set images for different resolutions:

<template>
  <vue-li
    srcset="image.jpg 1x, image_2x.jpg 2x"
  />
</template>

When using the srcset attribute is recommended to use also src as a fallback for browsers that don't support the srcset and sizes attributes:

<template>
  <vue-li
    srcset="image-320w.jpg 320w, image-480w.jpg 480w"
    sizes="(max-width: 320px) 280px, 440px"
    src="image-480w.jpg"
  />
</template>

The srcset prop is combinable with src-placeholder in order to apply progressive loading.

Picture

If you want to wrap the img in a picture tag, use the prop usePicture. You can then use slots to add additional elements above the img element`.

<vue-li
  srcset="image-320w.jpg 320w, image-480w.jpg 480w"
  alt="Fallback"
  use-picture
>
  <source srcset="image-320w.jpg 320w, image-480w.jpg 480w" />
</vue-li>

Renders as:

<picture>
  <source srcset="image-320w.jpg 320w, image-480w.jpg 480w" />
  <img srcset="image-320w.jpg 320w, image-480w.jpg 480w" alt="Fallback" />
</picture>

Note you can use the picture polyfill.

API

Aside from the following API, you can pass any img attribute, such as alt, and they'll be added to the rendered <img> tag.

Fields marked as (*) are required.

Props

| Name | Type | Default | Description | | ---------------------- | ------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | src | String (*) | - | Image src to lazy load when it intersects with the viewport | | src-placeholder | String | ' ' | If defined, it will be shown until the src image is loaded. Useful for progressive image loading, see demo | | src-fallback | String | ' ' | If defined, it will be shown if the src image fails to load | | srcset | String | - | Images to be used for different resolutions | | intersection-options | Object | () => ({}) | The Intersection Observer options object. | | use-picture | Boolean | false | Wrap the img in a picture tag. |

Events

| Name | Description | | ----------- | -------------------------------------------------------- | | intersect | Triggered when the image intersects the viewport | | load | Triggered when the lazy image defined in src is loaded | | error | Triggered when the lazy image defined in src fails to load |