Migration Guide
Migrating From v2 to v3
Install v3 of unlazy or of your adapter package first:
pnpm add unlazy@3
# or, for example
pnpm add @unlazy/vue@3The release notes list the fixes that need no change.
Code to Change
These changes need an edit in your code, markup, or build setup.
@unlazy/core Is Now unlazy
v3 ships no @unlazy/core. Import from unlazy instead:
- import { lazyLoad } from '@unlazy/core'
+ import { lazyLoad } from 'unlazy'
- import { createPngDataUri } from '@unlazy/core/blurhash'
+ import { createPngDataUri } from 'unlazy/blurhash'
- import { createPngDataUri } from '@unlazy/core/thumbhash'
+ import { createPngDataUri } from 'unlazy/thumbhash'The helpers only @unlazy/core exported – isSSR, toElementArray, debounce, createIndexedImagePlaceholder, and rgbaToDataUri – are gone. Copy the ones you used into your code.
Import UnLazySource From Your Adapter Package
Installing an adapter does not add unlazy to your dependencies, so import UnLazySource from the adapter package:
- import type { UnLazySource } from 'unlazy'
+ import type { UnLazySource } from '@unlazy/react'ES Modules Only
Every package ships ES modules only, without a CommonJS build or the main, module, and types fields. Replace require() with import. In TypeScript, set moduleResolution to "bundler" or "nodenext", since "node" reads no exports field and no longer finds the types.
Default Selector Is img[data-src], img[data-srcset]
lazyLoad() without a selector used to match:
img[loading="lazy"], img[loading="eager"][data-src], img[loading="eager"][data-srcset]It now matches:
img[data-src], img[data-srcset]An image with a data-src but no loading attribute used to be skipped. It now loads right away on the eager path. Add loading="lazy" to every image that should wait for the viewport:
- <img data-src="photo.jpg" alt="Photo">
+ <img loading="lazy" data-src="photo.jpg" alt="Photo">An <img loading="lazy"> without data-src or data-srcset is no longer matched, so it no longer logs the missing-attribute error.
triggerLoad Sets loading="eager"
triggerLoad and the preload option switch the image to loading="eager" as they swap in its source, so an off-screen image loads right away in every browser. Styles or scripts that select img[loading="lazy"] no longer match such an image afterwards. Select it by a class of your own instead.
@unlazy/nuxt Requires Nuxt 4
Upgrade your app to Nuxt 4 first – see Migrating to Nuxt 4.
Changed Behavior
These changes need no edit. Drop a workaround if you wrote one.
- Eager images and crawlers no longer get a hash placeholder, since the real image would replace it before it is painted. A
data-blurhashordata-thumbhashon an eager image does nothing. - With
loading="eager"and withoutautoSizes,UnLazyImagerenders the realsrc,srcset, andsourcesand no placeholder. For the LCP image, passsizesinstead ofautoSizes– see The Eager Path. onImageLoadfires once the visible image has loaded the real source, not once the preload has.lazyLoadnow callsonImageLoadoronImageErrorfor an image with its ownsrcorsrcsetand nodata-srcordata-srcset, even when it settled before the call, and a failed one getsdata-error. It no longer replaces theirsrcwith the hash placeholder or logs the missing-attribute error. Drop theloadanderrorlisteners you added for such an image, or its callback runs twice.- A failed image keeps its placeholder, in a
<picture>too, and gets adata-errorattribute until a later load succeeds – see Style a Failed Image. - A changed
src,srcSet, orsourcesloads the new image in every adapter. placeholderSizeis capped at100, so a larger value now decodes a 100-pixel BlurHash.- A BlurHash decodes square unless the image's
widthandheightare both known. Nuxt's server-decoded BlurHash is square without both attributes and withoutplaceholderRatio. - React: the package carries the
'use client'directive. Drop a'use client'wrapper you added aroundUnLazyImage. - Solid: the
solidexport condition lets SolidStart renderUnLazyImageon the server. Drop aclientOnlywrapper you added for it. - Nuxt:
placeholderRatiodefaults to the ratio of thewidthandheightattributes, so drop aplaceholder-ratiothat repeats them.@unlazy/nuxtno longer defines__UNLAZY_HASH_DECODING__astrue, so afalsedefine of yours now drops the hash placeholder of images withssr: false, lazy-loaded or held bylazy-load="false". - The missing-attribute error, the hash decoder failure error, and the LCP warning appear only where your bundler resolves the
developmentexport condition – see Disable Client Logging. The CDN builds log nothing. Drop a__UNLAZY_LOGGING__define offalsethat only kept the logs out of production.
Migrating From v1 to v2
Most users need a single find-and-replace. Install v2 first:
pnpm add unlazy@2Breaking Changes
loadImage Removal
The deprecated loadImage alias is gone. Replace every call site with triggerLoad:
- import { loadImage } from 'unlazy'
- loadImage(image, onLoad, onError)
+ import { triggerLoad } from 'unlazy'
+ triggerLoad(image, { onImageLoad: onLoad, onImageError: onError })triggerLoad Signature
triggerLoad now takes an options object instead of positional callbacks, and returns a cleanup function that detaches listeners and (for standalone images) aborts the in-flight network fetch:
- triggerLoad(image, onLoad, onError)
+ const cleanup = triggerLoad(image, { onImageLoad: onLoad, onImageError: onError })
+ // Optional: cleanup() to cancel before the load completesisLazyLoadingSupported Removal
Native loading="lazy" is Baseline Widely Available, so v2 drops the helper along with the fallback to an immediate swap. If you imported the helper directly, replace it with:
const isLazyLoadingSupported = 'loading' in HTMLImageElement.prototype…or assume true for any browser in your support matrix.
Expanded Default Selector
The default selector was:
img[loading="lazy"]It is now:
img[loading="lazy"], img[loading="eager"][data-src], img[loading="eager"][data-srcset]If you ever wrote <img loading="eager" data-src="..."> in v1, unlazy silently ignored it. In v2, unlazy processes it through the new eager-priority path. If you were relying on the silent no-op, pass a custom selector.
Native error Event on Preload Failure
Previously, when unlazy's off-DOM preload failed (404, decode error), the visible <img> never saw it – only the onImageError callback did. v2 dispatches a synthetic error event on the visible <img>, so native onerror / @error / onError now work for setting a fallback src:
<img loading="lazy" data-src="hero.jpg" onerror="this.src='/fallback.jpg'">If you bind both onImageError and a native error listener, both fire – pick whichever surface fits your app.
Vue / Nuxt: @image-load and @image-error Emits
The Vue and Nuxt adapters now expose a symmetric pair of emits aligned with the core option names:
| v1 | v2 |
|---|---|
@loaded="(image) => …" | @image-load="(image) => …" |
| – | @image-error="(image, error) => …" |
- <UnLazyImage @loaded="onLoaded" />
+ <UnLazyImage @image-load="onImageLoad" @image-error="onImageError" />The declared @error emit was removed.
INFO
Existing @error listeners keep working via Vue's attribute fallthrough – they fire for native errors and for the synthetic preload failure. Reach for @image-error only when you want both the wrapped image element and the event.
New Behavior
- unlazy now warns in development when the LCP element is still configured for lazy loading – see Dev-Mode LCP Warning.