v-photo

A Vue.js component to lazy load an image automatically when it enters the viewport using lazy Loading at the Browser-Level or as fallback Intersection Observer API.

Plugin is inspired by v-lazy-image.

Lazy Loading at the Browser-Level

v-photo is detects support for browser-level lazy loading and uses it as default. If browser-level lazy loading is not supported by browser fallback is Intersection Observer.

More information on: https://web.dev/native-lazy-loading/

Usage

npm install v-photo

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 vPhoto from 'v-photo';

Vue.use(vPhoto);

Or use it locally in any of your components:

import vPhoto from "v-photo";

export default {
  components: {
    vPhoto
  }
};

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

<template>
  <v-photo 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 is-loaded class is added, so you can use it to perform animations. For example, a blur effect:

<template>
  <v-photo
    src="http://lorempixel.com/400/200/"
    src-placeholder="http://lorempixel.com/200/200/"
  />
</template>

<style scoped>
.v-photo {
  filter: blur(10px);
  transition: filter 0.7s;
}
.v-photo.is-loaded {
  filter: blur(0);
}
</style>

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

<v-photo
  src="http://lorempixel.com/400/200/"
  :src-placeholder="require('../assets/img.jpg')"
/>

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

<template>
  <v-photo
    src="http://lorempixel.com/400/200/"
    src-placeholder="http://lorempixel.com/200/200/"
    @intersect="..."
    @load="..."
  />
</template>

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

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`.

<v-photo
  src="http://lorempixel.com/400/200/"
  alt="Fallback"
  use-picture
>
  <source srcset="http://lorempixel.com/1680/1024/" media="(min-width: 1024px)" />
</v-photo>

Renders as:

<picture>
  <source srcset="http://lorempixel.com/1680/1024/" media="(min-width: 1024px)" />
  <img srcset="http://lorempixel.com/400/200/" alt="Fallback" />
</picture>

Note you can use the picture polyfill.

API

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. | | alt | String | ' ' | img alt attribute | | intersection-options | Object | () => ({}) | The Intersection Observer options object. | | use-picture | Boolean | false | Wrap the img in a picture tag. | | use-lazy | Boolean | true | Turn off lazy loading |

Events

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