Installation

1# Yarn
2$ pnpm add vue-lazy-load-image-component
3
4# Pnpm
5$ pnpm i vue-lazy-load-image-component

LazyLoadImage usage

1<template>
2  <div>
3    <MyImage :image="image" />
4    <span>{{ image.caption }}</span>
5  </div>
6</template>
7<script lang="ts" setup>
8import { LazyLoadImage } from "vue-lazy-load-image-component";
9const image = ref({
10  alt: "My image",
11  height: 100,
12  src: "https://example.com/image.jpg",
13  width: 100,
14  caption: "My image caption",
15});
16</script>

Props

Prop	Type	Default	Description
afterLoad	Function		Function called after the image has been completely loaded.
beforeLoad	Function		Function called right before the placeholder is replaced with the image element.
delayMethod	String	throttle	Method from lodash to use to delay the scroll/resize events. It can be throttle or debounce.
delayTime	Number	300	Time in ms sent to the delayMethod.
effect	String		Name of the effect to use. Please, read next section with an explanation on how to use them.
placeholder	ReactClass	<span>	React element to use as a placeholder.
placeholderSrc	String		Image src to display while the image is not visible or loaded.
threshold	Number	100	Threshold in pixels. So the image starts loading before it appears in the viewport.
useIntersectionObserver	Boolean	true	Whether to use browser's IntersectionObserver when available.
visibleByDefault	Boolean	false	Whether the image must be visible from the beginning.
wrapperClassName	String		In some occasions (for example, when using a placeholderSrc) a wrapper span tag is rendered. This prop allows setting a class to that element.
wrapperProps	Object	null	Props that should be passed to the wrapper span when it is rendered (for example, when using placeholderSrc or effect)
...			Any other image attribute

Using effects

LazyLoadImage includes several effects ready to be used, they are useful to add visual candy to your application, but are completely optional in case you don't need them or want to implement you own effect.

They rely on CSS and the corresponding CSS file must be imported:

1<template>
2  <div>
3    <MyImage :image="image" />
4  </div>
5</template>
6<script lang="ts" setup>
7import { LazyLoadImage } from "vue-lazy-load-image-component";
8import "vue-lazy-load-image-component/lib/style.css";
9const image = ref({
10  alt: "My image",
11  height: 100,
12  src: "https://example.com/image.jpg",
13  width: 100,
14});
15</script>

The current available effects are:

• blur: renders a blurred image based on placeholderSrc and transitions to a non-blurred one when the image specified in the src is loaded.

• black-and-white: renders a black and white image based on placeholderSrc and transitions to a colorful image when the image specified in the src is loaded.

• opacity: renders a blank space and transitions to full opacity when the image is loaded.

LazyLoadComponent usage

1<template>
2  <div>
3    <LazyLoadComponent>
4      <MyComponent />
5    </LazyLoadComponent>
6  </div>
7</template>
8<script lang="ts" setup>
9import { LazyLoadComponent } from "vue-lazy-load-image-component";
10import MyComponent from "./MyComponent.vue";
11</script>

Props

Prop	Type	Default	Description
afterLoad	Function		Function called after the component has been rendered.
beforeLoad	Function		Function called right before the component is rendered.
delayMethod	String	throttle	Method from lodash to use to delay the scroll/resize events. It can be throttle or debounce.
delayTime	Number	300	Time in ms sent to the delayMethod from lodash.
placeholder	ReactClass	<span>	React element to use as a placeholder.
threshold	Number	100	Threshold in pixels. So the component starts loading before it appears in the viewport.
useIntersectionObserver	Boolean	true	Whether to use browser's IntersectionObserver when available.
visibleByDefault	Boolean	false	Whether the component must be visible from the beginning.

Using trackWindowScroll HOC to improve performance

When you have many elements to lazy load in the same page, you might get poor performance because each one is listening to the scroll/resize events. In that case, it's better to wrap the deepest common parent of those components with a HOC to track those events (trackWindowScroll).

For example, if we have an App which renders a Gallery, we would wrap the Gallery component with the HOC.

1<template>
2  <div>
3    <GalleryWithScrollTracking :images="images" />
4  </div>
5</template>
6<script lang="ts" setup>
7import { trackWindowScroll } from "vue-lazy-load-image-component";
8import Gallery from "./Gallery.vue";
9// Wrap Gallery with trackWindowScroll HOC so it receives
10// a scrollPosition prop to pass down to the images
11const images = ref([
12  {
13    alt: "My image",
14    height: 100,
15    src: "https://example.com/image.jpg",
16    width: 100,
17    scrollPosition: { x: 0, y: 0 },
18  },
19  {
20    alt: "My image 2",
21    height: 100,
22    src: "https://example.com/image2.jpg",
23    width: 100,
24    scrollPosition: { x: 0, y: 0 },
25  },
26]);
27
28const GalleryWithScrollTracking = trackWindowScroll(Gallery);
29</script>

You must set the prop scrollPosition to the lazy load components. This way, they will know the scroll/resize events are tracked by a parent component and will not subscribe to them.

Props

LazyLoadImage

Prop	Type	Default	Description
scrollPosition	Object		Object containing x and y with the curent window scroll position. Required.
afterLoad	Function		Function called after the image has been rendered.
beforeLoad	Function		Function called right before the image is rendered.
placeholder	ReactClass	<span>	React element to use as a placeholder.
threshold	Number	100	Threshold in pixels. So the image starts loading before it appears in the viewport.
visibleByDefault	Boolean	false	Whether the image must be visible from the beginning.
wrapperProps	Object	null	Props that should be passed to the wrapper span when it is rendered (for example, when using placeholderSrc or effect)
...			Any other image attribute

Component wrapped with trackWindowScroll (in the example, Gallery)

Prop	Type	Default	Description
delayMethod	String	throttle	Method from lodash to use to delay the scroll/resize events. It can be throttle or debounce.
delayTime	Number	300	Time in ms sent to the delayMethod from lodash.
useIntersectionObserver	Boolean	true	Whether to use browser's IntersectionObserver when available.

Notice you can do the same replacing LazyLoadImage with LazyLoadComponent.

When to use visibleByDefault?

The prop visibleByDefault makes the LazyLoadImage to behave like a normal <img>. Why is it useful, then?

Imagine you are going to lazy-load an image you have already loaded in the same page. In that case, there is no need to lazy-load it because it's already stored in the cache of the user's browser. You can directly display it.

Maybe the following code snippet will make it more clear:

1<template>
2  <div>
3    <img src="/landscape.jpg" alt="Beautiful landscape" />
4    <GalleryWithScrollTracking :images="images" />
5  </div>
6</template>
7<script lang="ts" setup>
8import { trackWindowScroll } from "vue-lazy-load-image-component";
9import Gallery from "./Gallery.vue";
10const images = ref([
11  {
12    alt: "My image",
13    height: 100,
14    src: "https://example.com/image.jpg",
15    width: 100,
16  },
17  {
18    alt: "My image 2",
19    height: 100,
20    src: "https://example.com/image2.jpg",
21    width: 100,
22    // If the image we are creating here has the same src than before,
23    // we can directly display it with no need to lazy-load.
24    visibleByDefault: image.src === "/landscape.jpg",
25  },
26]);
27
28const GalleryWithScrollTracking = trackWindowScroll(Gallery);
29</script>

reference

react-lazy-load-image-component