unlazy

Universal lazy loading library leveraging native browser APIs.

• 🎀 Native: Utilizes the loading="lazy" attribute
• 🌊 BlurHash & ThumbHash support: SSR & client-side decoding
• ⚡ Core Web Vitals-aware: Eager-priority path for above-the-fold images, dev-mode LCP warning
• 🎟 <picture>: Art direction with automatic sizes

Installation

# pnpm
pnpm add unlazy

# npm
npm i unlazy

Quick Start

<img
  loading="lazy"
  src="data:image/svg+xml, ..."
  data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
  data-sizes="auto"
  alt="Descriptive text"
  width="640"
  height="360"
>

import { lazyLoad } from 'unlazy'

// Processes `img[loading="lazy"]` and `img[loading="eager"][data-src|data-srcset]`
const cleanup = lazyLoad()

For above-the-fold / LCP images, use loading="eager" – unlazy swaps the source immediately and applies fetchpriority="high" for you.

Documentation

📖 Read the full documentation, including hash-based placeholders, Core Web Vitals, and SSR.

Migrating from v1

See the migration guide for breaking changes in v2.

License

MIT License © 2023-PRESENT Johann Schopplich