Codakey
Play
← Back to tuupola/jquery_lazyload

How to Deploy & Use tuupola/jquery_lazyload

Lazy Load Remastered - Deployment & Usage Guide

Prerequisites

  • Browser Support: Modern browsers with Intersection Observer API support (Chrome 51+, Firefox 55+, Safari 12.1+, Edge 15+)
  • Fallback: For IE11 or older Safari, include a polyfill
  • Build Tools (optional): If using npm/yarn integration, Node.js 10+ recommended
  • jQuery (optional): Only if using the jQuery wrapper

Installation

Option 1: CDN (Recommended for Quick Start)

<script src="https://cdn.jsdelivr.net/npm/lazyload@2.0.0-rc.2/lazyload.js"></script>

For production, use the minified version:

<script src="https://cdn.jsdelivr.net/npm/lazyload@2.0.0-rc.2/lazyload.min.js"></script>

Option 2: Package Manager

# npm
npm install lazyload

# yarn
yarn add lazyload

Then import in your project:

// ES6 modules
import LazyLoad from 'lazyload';

// CommonJS
const LazyLoad = require('lazyload');

Option 3: Download

Download lazyload.js or lazyload.min.js directly from the repository and include:

<script src="path/to/lazyload.min.js"></script>

Configuration

HTML Data Attributes

Configure image sources using data attributes:

<!-- Basic usage -->
<img class="lazyload" data-src="img/example.jpg" width="765" height="574" />

<!-- With low-res placeholder (blur-up technique) -->
<img class="lazyload" src="img/thumb.jpg" data-src="img/example.jpg" width="765" height="574" />

<!-- Responsive images -->
<img class="lazyload"
     src="thumbnail.jpg"
     data-src="large.jpg"
     data-srcset="small.jpg 480w, medium.jpg 640w, large.jpg 1024w"
     width="1024" height="768" />

<!-- Background images -->
<div class="lazyload"
     style="background-image: url('thumbnail.jpg')"
     data-src="original.jpg">
</div>

JavaScript Configuration Options

Pass options as the second argument to the constructor:

const lazy = new LazyLoad(images, {
    src: "data-src",           // Attribute containing image URL
    srcset: "data-srcset",     // Attribute containing srcset
    selector: ".lazyload",     // CSS selector for auto-initialization
    root: null,                // IntersectionObserver root element
    rootMargin: "0px",         // Margin around root (e.g., "100px")
    threshold: 0               // Visibility threshold (0-1)
});

Intersection Observer Settings:

  • root: Viewport element (null = browser viewport)
  • rootMargin: Preload margin (e.g., "200px" loads images 200px before they enter viewport)
  • threshold: Trigger point (0 = when first pixel visible, 1 = when fully visible)

jQuery Configuration

jQuery wrapper uses data-original by default for backwards compatibility:

<img class="lazyload" data-original="img/example.jpg" width="765" height="574">

$("img.lazyload").lazyload();

Build & Run (Local Development)

Basic HTML Setup

Create an index.html file:

<!DOCTYPE html>
<html>
<head>
    <title>Lazy Load Test</title>
    <style>
        img { display: block; margin: 1000px 0; } /* Force scrolling */
    </style>
</head>
<body>
    <img class="lazyload" data-src="image1.jpg" width="800" height="600" />
    <img class="lazyload" data-src="image2.jpg" width="800" height="600" />
    
    <script src="https://cdn.jsdelivr.net/npm/lazyload@2.0.0-rc.2/lazyload.js"></script>
    <script>
        // Initialize
        const lazy = lazyload();
    </script>
</body>
</html>

Module Bundler Integration (Webpack/Rollup)

import LazyLoad from 'lazyload';

document.addEventListener("DOMContentLoaded", function() {
    const lazyLoadInstance = new LazyLoad({
        elements_selector: ".lazyload",
        threshold: 300
    });
});

Testing Locally

  1. Serve files via local server (required for Intersection Observer):
# Python 3
python -m http.server 8000

# Node.js (npx)
npx serve .

# PHP
php -S localhost:8000
  1. Open browser console to verify images load on scroll
  2. Check Network tab to confirm delayed loading

Deployment

Production Optimization

1. Preload Critical Images For above-the-fold images, skip lazy loading to improve LCP (Largest Contentful Paint):

<!-- Critical image: load immediately -->
<img src="hero.jpg" width="1200" height="600" />

<!-- Below-fold: lazy load -->
<img class="lazyload" data-src="section1.jpg" />

2. SEO & Accessibility Always include width and height attributes to prevent layout shift (CLS). For SEO-critical images, provide <noscript> fallback:

<img class="lazyload" data-src="important.jpg" width="800" height="600" />
<noscript>
    <img src="important.jpg" width="800" height="600" />
</noscript>

3. CSP (Content Security Policy) If using strict CSP, allow data: URIs for inlined placeholders:

<img src="data:image/gif;base64,R0lGODdhAQABAPAAAMPDwwAAACwAAAAAAQABAAACAkQBADs="
     data-src="original.jpg" />

4. Deployment Platforms Since this is a client-side library, deploy as part of your frontend:

  • Static Sites (Netlify, Vercel, GitHub Pages): Include the script in your build output
  • CDN: Use jsDelivr or unpkg for zero-build deployment
  • WordPress: Enqueue via wp_enqueue_script() with jQuery dependency if using wrapper

5. Performance Budget Monitor bundle size:

  • Minified: ~2KB (gzipped)
  • If using polyfill for IE11: Add ~6KB

Troubleshooting

Images Not Loading

Symptom: Images remain blank when scrolling into view

  • Check: Verify data-src attribute exists and URL is correct
  • Check: Ensure images have class="lazyload" or match your selector
  • Check: Confirm JavaScript initialized after DOM loaded:
document.addEventListener("DOMContentLoaded", function() {
    lazyload();
});

Intersection Observer Errors

Symptom: IntersectionObserver is not defined in IE11 or older Safari

  • Solution: Include polyfill before lazyload:
<script src="https://polyfill.io/v3/polyfill.min.js?features=IntersectionObserver"></script>
<script src="lazyload.min.js"></script>

Layout Shift (CLS)

Symptom: Page content jumps as images load

  • Solution: Always include explicit width and height attributes on <img> tags
  • Solution: Use low-res placeholder in src attribute

jQuery Wrapper Not Working

Symptom: $(...).lazyload is not a function

  • Check: Ensure jQuery loads before the lazyload script
  • Check: Use data-original not data-src for jQuery version
  • Check: jQuery wrapper requires explicit class selection: $("img.lazyload")

Background Images Not Loading

Symptom: Divs with data-src don't show background images

  • Check: Ensure element has class="lazyload"
  • Check: Verify CSS doesn't override background-image with !important

Memory Leaks

Symptom: Performance degrades on long-running SPAs

  • Solution: Call destroy() when removing DOM elements:
const lazy = lazyload();
// Later, when cleaning up
lazy.destroy();

Force Load All Images

Use case: Print view or "Load all" button

lazy.loadImages();      // Load remaining images
// OR
lazy.loadAndDestroy();  // Load and cleanup observer
← Project overviewView alternatives to tuupola/jquery_lazyload →