unlazy Documentation

unlazy is a universal, framework-agnostic lazy loading library designed for placeholder images. It leverages native browser APIs like loading="lazy" to provide efficient image loading.

Key capabilities include:

• Placeholder Support: Uses BlurHash and ThumbHash compact hash strings to decode into blurry placeholder images.
• Flexible Decoding: Supports SSR (Server-Side Rendering) decoding or client-side decoding at runtime.
• Auto-Sizing: Automatically calculates the sizes attribute based on display width.
• SEO Optimization: Detects bots and crawlers to load full images immediately for indexing.
• Broad Compatibility: Works with any framework or no framework at all. Dedicated integrations are available for Vue, React, Solid, Svelte, and Nuxt.

The unlazy library provides several utility functions for managing lazy loading, placeholder generation, and image handling.

Key functions include:

• lazyLoad: Initializes lazy loading with placeholder generation.
• autoSizes: Calculates the sizes attribute for responsive images without using lazy loading.
• triggerLoad: Programmatically forces an image to load immediately.
• createPlaceholderFromHash: Generates a PNG data URI from a hash on the client-side.
• createPngDataUri (from unlazy/blurhash): Generates a PNG data URI from a BlurHash (optimized for SSR).
• createPngDataUri (from unlazy/thumbhash): Generates a PNG data URI from a ThumbHash (optimized for SSR).

unlazy provides official integrations for several frontend and meta-frameworks. Each integration provides a UnLazyImage component designed as a drop-in replacement for the native <img> element.

Frontend Frameworks

• Vue
• React
• Solid
• Svelte

Meta-Frameworks

• Nuxt (Supports SSR-decoding of hash-based placeholders like BlurHash and ThumbHash)

The @unlazy/react component provides several optimized image loading capabilities:

• Native Lazy Loading: Uses the browser's native loading="lazy" attribute.
• Hash-based Placeholders: Supports BlurHash and ThumbHash for both SSR and client-side decoding.
• Core Web Vitals Optimization: Includes an eager-priority path for above-the-fold images and provides LCP (Largest Contentful Paint) warnings in development mode.
• Art Direction: Supports the <picture> element with automatic sizes attribute management.

unlazy is a lazy loading library that enhances the native browser loading="lazy" attribute to improve perceived performance. It uses inlined placeholder images (like BlurHash or ThumbHash) that swap to full-quality versions as images enter the viewport.

Core Mechanisms:

• Attribute Swapping: It uses data-src, data-srcset, and data-sizes attributes. These are swapped to standard src, srcset, and sizes attributes once the image loads.
• Placeholder Decoding: It decodes hash-based strings (BlurHash/ThumbHash) into PNG data URIs for initial rendering.
• Chrome Workaround: It uses unique indexed SVG placeholders to prevent Chrome from prematurely triggering load events.
• Auto Sizes: If data-sizes="auto" is provided, unlazy calculates the sizes attribute based on the image's display width.

To ensure search engine bots and crawlers index high-quality images instead of blurry placeholders, unlazy uses an isCrawler constant to detect non-human visitors.

When a crawler is detected via User Agent scanning or by checking for onscroll support, unlazy immediately converts data-srcset and data-src attributes into their standard srcset and src counterparts. This allows bots to see and index the full-quality image sources directly.

Client-Side Decoding

• Mechanism: Uses data-blurhash or data-thumbhash attributes.
• Pros: Placeholders are visible immediately on page load.
• Cons: Increases client-side JavaScript bundle size because the decoding library must be included.

Server-Side Decoding

• Mechanism: Uses createPngDataUri to embed a PNG data URI in the src attribute.
• Pros: Keeps client bundle smaller; ideal for minimizing JavaScript.
• Cons: Requires server-side processing logic.

unlazy is designed to work with crawlers and social scrapers (like Googlebot, Slackbot, Twitterbot, and facebookexternalhit).

Because many scrapers do not execute JavaScript or scroll the page, unlazy detects bot user agents and executes an immediate-swap path. This ensures that crawlers see the real src attribute in the rendered HTML rather than just the data-src placeholder.

During development, unlazy uses a PerformanceObserver to monitor largest-contentful-paint entries. If the detected LCP element is an <img> that is still configured for lazy loading (i.e., it has loading="lazy" or is still using data-src/data-srcset), unlazy will log a warning to the console:

[unlazy] LCP element is configured for lazy loading. Set loading="eager" to improve Largest Contentful Paint.

To remove these warnings from production builds, use the __UNLAZY_LOGGING__ build flag.