@hzzt/v-lazy-image
v1.4.2
Published
A Vue.js component to lazy load images using the Intersection Observer.
Downloads
3
Readme
v-lazy-image
A Vue.js component to lazy load an image automatically when it enters the viewport using the Intersection Observer API.
Do you know VueDose? It's where you can learn tips about the Vue.js ecosystem in a concise format, perfect for busy devs! 🦄
Demos
- Simple demo
- Responsive images, by @aarongarciah
- Progressive image loading with animations, by @aarongarciah
- Performant progressive blur using SVG
Usage
npm install v-lazy-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 { VLazyImagePlugin } from "v-lazy-image";
Vue.use(VLazyImagePlugin);
Or use it locally in any of your components:
import VLazyImage from "v-lazy-image";
export default {
components: {
VLazyImage
}
};
You must pass an src
property with the link of the image:
<template>
<v-lazy-image 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 v-lazy-image-loaded
class is added, so you can use it to perform animations. For example, a blur effect:
<template>
<v-lazy-image
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>
.v-lazy-image {
filter: blur(10px);
transition: filter 0.7s;
}
.v-lazy-image-loaded {
filter: blur(0);
}
</style>
In case you are using Webpack bundler for images too (just like Vue-cli):
<v-lazy-image
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>
<v-lazy-image
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>
<v-lazy-image
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>
<v-lazy-image
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`.
<v-lazy-image
srcset="image-320w.jpg 320w, image-480w.jpg 480w"
alt="Fallback"
use-picture
>
<source srcset="image-320w.jpg 320w, image-480w.jpg 480w" />
</v-lazy-image>
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 |
| 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 |