2.0.1 • Public • Published


npm version npm downloads License

This module offers you a <LazyImage> Component which handles lazy loading for images.

⚠️ Please note that this module has an dependency to @bazzite/nuxtoptimizied-images module.




  • Lazy Loading is enabled through popular lazysizes library.
  • Since we're using nuxt-optimizied-images under the hood you will get optimizied images out of the box.

🎯 Install

yarn add nuxt-lazyimage @bazzite/nuxt-optimized-images
# npm install nuxt-lazyimage nuxt-optimizied-images 

As described in the nuxt-optimized-images module documentation you need to install the appropiate loaders for your project.

yarn add -D responsive-loader imagemin-mozjpeg webp-loader lqip-loader
# npm install --save-dev responsive-loader imagemin-mozjpeg webp-loader 

Add modules to nuxt.config.js

  modules: [
    // Simple usage
    // With options
    ['nuxt-lazyimage', { /* module options */ }],
    ['@bazzite/nuxt-optimized-images', { /* module options */ }],

📌 Configuration

  lazyImage: {
    defaultCss: true // should defaultCSS be included?

🚀 Usage

⚠️ Important The reason why you need to set the width and height manually is that I want to avoid fixed CSS heights or js width/height calculations. The way I do it is mainly via CSS aspect-ratios. You can see an implementation in the current [example] code ( or you can dig older examples here on Codepen, Codesandbox and nuxt-lazysizes-aspect-ratio-blur.

Simple Usage

Simple Example with default path ~/assets/images/cat.jpg

Notice: Aspect-Ratio is a custom class which isn't included - read above

<LazyImage data-src="cat.jpg" class="aspect-ratio-16/9" />

You can use some external image url too

<LazyImage data-src="" class="aspect-ratio-16/9" />

Load an image through some path.

Be careful you need to use require() for this scenario nuxt.js#448, vuejs#202

<LazyImage data-src="require(`~/assets/media-folder/dog.jpg`)" class="aspect-ratio-16/9" :ignore-img-base-path="true" />

Smooth Parallax Scrolling

If you like smooth scrolling for your images you can combine locomotive-scroll with nuxt-lazyimage.

Simple smooth scroll


Add more scrolling speed (even negative)


You can also add some nice effect with inside scrolling


Viewport Transition Effects

Simple fade in effect for your image

  class="aspect-ratio-16/9 a-fadein"

Some more effects...

  effect="a-reveal a-reveal-left-to-right"
  effect="a-reveal a-reveal-top-to-bot"

⚠️ Important Unfortunately transitions and smooth-scrolling are currently tightly coupled to locomotive-scroll viewport library which I personally prefer using atm. That means you definitly need a custom library that gives you an active class on the element if the image scrolls into the current viewport. Also the animations.css file uses is-inview class from locomotive.

To get it work with other viewport libraries you need to tweak some elements inside the Component. Or you just wrap the <LazyImage /> with some custom directive and code the animation right away. For example Akryum/vue-observer-visibility works very well.

I think this needs some refactoring to be able to set your active classes yourself - feel free to adapt.

Use lqip with blur-up technique

Example with lqip-loader

You need to install lqip-loader first!

<LazyImage data-src="cat.jpg" :use-lqip="true" />

Some more examples

Choose between object-fit: cover and contain.

It uses lazysizes/plugins/object-fit/ls.object-fit behind the scene

<LazyImage data-src="cat.jpg" objectFit="contain" />
<LazyImage data-src="cat.jpg" objectFit="cover" /> <!-- default -->

API Reference


Name Description Type Required Default
dataSrc The image URL you want to show 'cat.jpg' true -
objectFit Specify how the image/video will fit the container 'cover' / 'contain' false 'cover'
smoothScrollType Enable animation wrapper. Works currently only with locomotive library 'none' / 'outside' / 'inside' false 'none'
effect Define the animation effect you want to use 'a-reveal' / 'a-fadein' / 'custom' false ''
scrollSpeed Everything > 0 gets an smooth parallax scroll. Works only with locomotive library! String false '0'
ignoreImgBasePath The default path is ~/assets/images. Boolean false false
useSrcSet If you disable this prop you will get a simple tag Boolean false true
useLqip Use LQIP/blurry image placeholder/Blur up image technique. Needs lqip-loader Boolean false false


Name Description Default Slot Content
default - -


  1. Add more flexibility for different viewport libraries
  2. Add possibility to use more custom attributes (like scroll-orientation)


  1. Clone this repository
  2. Install dependencies using yarn install or npm install
  3. Start development server using npm run dev


  • Currently there is no SSR Support !


MIT License

Copyright (c) Kevin Regenrek




Package Sidebar


npm i nuxt-lazyimage

Weekly Downloads






Unpacked Size

20.8 kB

Total Files


Last publish


  • regenrek