Lazy Pix

Lazy Pix is a simple Vue and Nuxt plugin to lazy-load images (background images and <img> supported). lazy-pix aims to be lightweight (<1kb), flexible and customizable.

Features

• 💯 Simple & Lightweight
• 💯 Typescript
• ✨ SSR friendly
• ✅ Vue & Nuxt
• ✅ Customizable

Installation

pnpm add lazy-pix

npm install lazy-pix

yarn add lazy-pix

You should probably only choose one :)

Setup

Vue 3

Import vLazyPix in main file

import { vLazyPix } from 'lazy-pix';
// then
app.use(vLazyPix);

Nuxt 3

Create a file with any name under src/plugins and paste the following:

import { useLazyPix } from 'lazy-pix';

const lazyPix = useLazyPix();

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.directive('lazy-pix', lazyPix);
});

Usage

The package exposes a directive v-lazy-pix (that you can choose to rename, Customization). The directive uses IntersectionObserver (MDN) to track and load the image just before it enters the viewport. In really old browsers where IntersectionObserver is not supported, the image is loaded normally.

For the full gist on the implementation, read The Complete Guide to Lazy Loading Images by Rahul Nanwani.

Lazy loading <img>

Add v-lazy-pix to an image element and pass it the src.

<template>
  <img src="url/to/image.jpg">
  <!-- becomes -->
  <img v-lazy-pix="'url/to/image.jpg'">
</template>

Note: The URL must be resolved or absolute. See Gotchas below.

Also, if you want, you could add/style a placeholder image in the src. The placeholder will automatically be replaced.

<template>
  <img src="url/to/image.jpg">
  <!-- becomes -->
  <img v-lazy-pix="'url/to/image.jpg'" src="placeholder.png">
</template>

Lazy loading background images

Background images take a slightly different approach to give you full flexibility.

First off, add a bg arg to v-lazy-pix

- v-lazy-pix
+ v-lazy-pix:bg

- v-lazy-pix=""
+ v-lazy-pix:bg=""

Lazy loading background images work by adding a class to the element when the image is ready to be loaded. The default "ready" class is img-ready but you can change it however you want (Customization).

<template>
  <div v-lazy-pix:bg class="target">
    Background Image, Text Overlay
  </div>
</template>

<style>
.target {
  /* fallback color, background position, styles... */
}
.target.img-ready {
  /* the magic happens here */
  background-image: url("./path/to/image.png");
}

/* using bg shorthand and css variable */
.target {
  --img: url("");
  background: #7a1f1f var(--img);
}
.target.img-ready {
  --img: url("./path/to/image.jpg");
}

/* Pseudo elements? Why not! */
.target::before {
  /* styles... */
}
.target.img-ready::before {
  --img: url("./path/to/image.gif");
}
</style>

Customization

The default "ready" class is img-ready but you can cutomize it globally and per element.

To customize ready class for an element, pass a string (or string variable) to the directive.

Ready class per element

Note: Bg images only. Per-element classes will always override global.

<template>
  <div v-lazy-pix:bg="'yes-image'">
    This div has a bg-img
  </div>
  <div v-lazy-pix:bg="myReadyClass">
    This div has a bg-img
  </div>
</template>

Vue Globally

Pass an options object as the second param to app.use(). For better intellisense, import lazyConfig().

import { lazyConfig, vLazyPix } from 'lazy-pix';
// ...
app.use(vLazyPix, lazyConfig({
  // maybe you don't like `v-lazy-pix`?
  name: 'v-lazy-img',
  // customize ready class(es)
  class: 'load-img img-loaded',
}));

Nuxt Globally

import { useLazyPix } from 'lazy-pix';

// change the default ready class
// --> useLazyPix(readyClass)
const lazyPix = useLazyPix('ready-to-go');

export default defineNuxtPlugin((nuxtApp) => {
  // change the directive name here
  // nuxtApp.vueApp.directive(name, directive);
  nuxtApp.vueApp.directive('lazy-picasso', lazyPix);
  // or...
  nuxtApp.vueApp.directive('lazy-picasso', useLazyPix('ready-class'));
});

Gotchas

There are a few things to take note of:

• When lazy loading <img> with Vite, you need to pass an absolute or resolved image URL due to Vite's Static Asset Handling. This doesn't apply to background images, though.
• This plugin does not support loading multiple images as in srcset or sources. To do that use the browser's loading="lazy".
• On browsers without IntersectionObserver support, the images are loaded normally. While it is possible to lazy load using scroll/resize event listeners, it is less efficient and too much of it can lead to a negative impact on performance. From the frying pan into fire, they say.

License

MIT License © 2023 ML