feat: fallback if loading="lazy" unsupported

Author: johannschopplich

README.md

@@ -185,7 +185,7 @@ Keep in mind that manually loading images might negatively affect the perceived
 
 ## API
 
-### `lazyLoadImages(selectors: string)`
+### `lazyLoadImages(selectors)`
 
 The main method of the library. It works as follows:
 
@@ -194,15 +194,62 @@ The main method of the library. It works as follows:
 3. If the image has a blurry placeholder and is already in the viewport or the visitor is a crawler, it immediately loads the full-quality image.
 4. If the image is not yet in the viewport, an event listener is added to load the full-quality image when it enters the viewport.
 
+**Type Declaration**
+
+```ts
+function lazyLoadImages(
+  /**
+   * A CSS selector or a list of CSS selectors to match images to lazy load.
+   *
+   * @default 'img[loading="lazy"]'
+   */
+  selectors?: string,
+  /**
+   * A callback function to run when an image is loaded.
+   */
+  onLoaded?: (image: HTMLImageElement) => void
+): void
+```
+
 #### `selectors`
 
 Defaults to `img[loading="lazy"]`. Allowed types are a valid CSS selector string.
 
-### `autoSizes(selectors: string)`
+#### `onLoaded`
+
+An optional callback function to run when an image is loaded. It accepts an `HTMLImageElement` as a parameter.
+
+### `autoSizes(selectors)`
+
+**Type Declaration**
+
+```ts
+function autoSizes(
+  /**
+   * A CSS selector or a list of CSS selectors to calculate the `sizes` attribute for.
+   *
+   * @default 'img[data-sizes="auto"], source[data-sizes="auto"]'
+   */
+  selectors?: string
+): void
+```
+
+#### `selectors`
 
 Defaults to `img[data-sizes="auto"], source[data-sizes="auto"]`. Allowed types are a valid CSS selector string.
 
-### `loadImage(element: HTMLImageElement)`
+### `loadImage(element)`
+
+**Type Declaration**
+
+```ts
+function loadImage(
+  image: HTMLImageElement,
+  onLoaded?: (image: HTMLImageElement) => void
+): void
+```
+
+#### `element`
 
 An instance of `HTMLImageElement` representing the image you want to load manually.
 

src/index.ts

@@ -1,3 +1,4 @@
+export const isLazyLoadingSupported = 'loading' in HTMLImageElement.prototype
 export const isCrawler = !('onscroll' in window) || /(gle|ing|ro)bot|crawl|spider/i.test(navigator.userAgent)
 
 export function lazyLoadImages(
@@ -10,7 +11,7 @@ export function lazyLoadImages(
   /**
    * A callback function to run when an image is loaded.
    */
-  onLoad?: (image: HTMLImageElement) => void,
+  onLoaded?: (image: HTMLImageElement) => void,
 ) {
   for (const image of [...document.querySelectorAll<HTMLImageElement>(selectors)]) {
     // Calculate the image's `sizes` attribute if `data-sizes="auto"` is set
@@ -20,22 +21,22 @@ export function lazyLoadImages(
     if (!image.dataset.srcset)
       continue
 
-    if (isCrawler) {
-      // Let the crawler load the image
+    // Use the same logic as for crawlers when native lazy-loading is not supported
+    if (isCrawler || !isLazyLoadingSupported) {
       updatePictureSources(image)
       updateImageSrcset(image)
-      onLoad?.(image)
+      onLoaded?.(image)
       continue
     }
 
     if (image.complete && image.naturalWidth > 0) {
       // Load the image if it's already in the viewport
-      loadImage(image, onLoad)
+      loadImage(image, onLoaded)
       continue
     }
 
     // Otherwise, load the image when it enters the viewport
-    image.addEventListener('load', () => loadImage(image, onLoad), { once: true })
+    image.addEventListener('load', () => loadImage(image, onLoaded), { once: true })
   }
 }
 
@@ -53,7 +54,7 @@ export function autoSizes(
 
 export function loadImage(
   image: HTMLImageElement,
-  onLoad?: (image: HTMLImageElement) => void,
+  onLoaded?: (image: HTMLImageElement) => void,
 ) {
   const imageLoader = new Image()
   imageLoader.srcset = image.dataset.srcset!
@@ -62,12 +63,11 @@ export function loadImage(
   imageLoader.addEventListener('load', () => {
     updatePictureSources(image)
     updateImageSrcset(image)
-    onLoad?.(image)
+    onLoaded?.(image)
   })
 }
 
 export default Object.freeze({
-  isCrawler,
   lazyLoadImages,
   autoSizes,
   loadImage,

vite.config.ts

@@ -1,12 +1,14 @@
 import { resolve } from 'node:path'
 import { defineConfig } from 'vite'
 
+const currentDir = new URL('.', import.meta.url).pathname
+
 export default defineConfig({
   build: {
     // minify: false,
     // target: 'esnext',
     lib: {
-      entry: resolve(__dirname, 'src/index.ts'),
+      entry: resolve(currentDir, 'src/index.ts'),
       name: 'unlazy',
       formats: ['es', 'umd', 'iife'],
     },