# lazysizes — High-Performance Lazy Loader for Images and Iframes

> A self-initializing lazy loader for images, iframes, and responsive images that detects visibility changes through user interaction, CSS, or JavaScript.

## Install

Save in your project root:

# lazysizes — High-Performance Lazy Loader for Images and Iframes

## Quick Use
```bash
npm install lazysizes
```
```html
<script src="lazysizes.min.js" async></script>
<img data-src="image.jpg" class="lazyload" alt="example" />
<img data-srcset="small.jpg 300w, large.jpg 600w" data-sizes="auto" class="lazyload" alt="responsive" />
```

## Introduction
lazysizes is a fast, SEO-friendly lazy loader that defers loading of images, iframes, and other elements until they approach the viewport. It requires no configuration — add the `lazyload` class and swap `src` to `data-src`, and the library handles the rest.

## What lazysizes Does
- Defers loading of images and iframes until they are near the visible viewport
- Automatically calculates the `sizes` attribute for responsive images
- Detects visibility changes from scrolling, resizing, CSS transitions, and DOM mutations
- Prioritizes elements that are closest to the current viewport position
- Supports native loading="lazy" as a progressive enhancement

## Architecture Overview
lazysizes uses a combination of Intersection Observer (where available) and a fallback scroll/resize listener with request idle callback batching. It monitors DOM mutations via MutationObserver to pick up dynamically added elements. A priority queue ensures that elements closest to the viewport load first. The core is extensible through a plugin system that hooks into lifecycle events.

## Self-Hosting & Configuration
- Include the script with `async` attribute for non-blocking load
- Add `class="lazyload"` and `data-src` to any image or iframe element
- Set `data-sizes="auto"` to let lazysizes calculate responsive sizes
- Configure `lazySizesConfig.expand` to control the preload distance in pixels
- Load plugins like `unveilhooks` for background images or video posters

## Key Features
- Zero-configuration setup: just add a class and a data attribute
- Automatic `sizes` calculation for `srcset` responsive images
- SEO-friendly: works with search engine crawlers that execute JavaScript
- Plugin architecture for background images, LQIP patterns, and video elements
- Stable API that has powered production sites for years

## Comparison with Similar Tools
- **Native loading="lazy"** — browser-built-in but no auto-sizes, no priority queue, and inconsistent thresholds
- **lozad.js** — lighter but lacks auto-sizes, priority loading, and the plugin ecosystem
- **vanilla-lazyload** — similar feature set but lazysizes has broader plugin support and mutation detection
- **react-lazyload** — React-specific wrapper; lazysizes works across any framework or vanilla HTML

## FAQ
**Q: Does lazysizes affect SEO?**
A: No. Search engines that execute JavaScript see the loaded images. For crawlers that do not, use a `noscript` fallback.

**Q: How do I lazy-load background images?**
A: Include the `unveilhooks` plugin and use `data-bg="url"` with the `lazyload` class.

**Q: Can I use lazysizes with React or Vue?**
A: Yes. Import the library in your entry file. The MutationObserver picks up dynamically rendered elements automatically.

**Q: What is the preload distance?**
A: By default, lazysizes starts loading elements 370px before they enter the viewport. Adjust with `lazySizesConfig.expand`.

## Sources
- https://github.com/aFarkas/lazysizes
- https://afarkas.github.io/lazysizes/

---
Source: https://tokrepo.com/en/workflows/asset-a9723ede
Author: AI Open Source