triggerLoad

The triggerLoad function programmatically loads an image by swapping its data attributes to standard ones. It handles both standalone <img> elements and images inside <picture> elements.

The function performs the following operations:

1. If the image is inside a <picture> element, swaps data-srcset to srcset on every <source> and resolves data-sizes="auto" to a numeric pixel width before the swap so the browser sees a final value at source-selection time. Callbacks fire after the browser resolves a source on the visible <img>.
2. For standalone <img> elements, preloads the image in a temporary element to ensure proper loading.
3. Calculates the sizes attribute on the temporary element if data-sizes="auto" is set on the visible <img>.
4. Swaps data-src and data-srcset to their standard counterparts.
5. Invokes the optional onImageLoad callback when loading completes, or onImageError if loading fails. On failure, a synthetic error event also fires on the visible <img>.

triggerLoad returns a cleanup function that detaches its listeners and, for standalone images, aborts the in-flight network fetch. Calling it after the load has already completed is a no-op.

TIP

triggerLoad is one-shot – it does not install any ResizeObserver. For ongoing source-size tracking on responsive <picture> layouts, pair it with autoSizes and { updateOnResize: true }:

const cleanupSizes = autoSizes(image, { updateOnResize: true })
const cleanupLoad = triggerLoad(image)

// Later
cleanupSizes()
cleanupLoad()

Type Declarations

/**
 * Triggers the loading of a lazy image by swapping `data-src`/`data-srcset` to `src`/`srcset`.
 *
 * @returns A cleanup function that detaches listeners and, for standalone images, aborts any
 * in-flight network fetch by clearing the temporary image's `src`. Calling it after the
 * load completes is a no-op.
 *
 * @remarks
 * For standalone `<img>` elements, the image is preloaded via a temporary `Image` before
 * the swap; `onImageLoad` fires on success and `onImageError` on failure. On failure unlazy
 * also dispatches a synthetic `error` event on the visible `<img>` so consumers using
 * native `addEventListener('error', …)` or framework-native `onError` / `@error` get notified.
 *
 * For `<img>` elements inside `<picture>`, the browser handles source selection. Listeners
 * are attached on the visible `<img>` before the swap so the queued `load` task is caught
 * once the browser resolves a source. If `data-src` resolves to the URL already on the
 * `<img>`, the browser fires no `load` event and the callback never runs.
 *
 * `triggerLoad` does not install a `ResizeObserver`. Pair it with
 * `autoSizes(img, { updateOnResize: true })` for ongoing source-size tracking.
 */
export function triggerLoad(
  image: HTMLImageElement,
  options?: TriggerLoadOptions,
): () => void

Example

import { triggerLoad } from 'unlazy'

const image = document.querySelector<HTMLImageElement>('.priority-image')!

// Load immediately with callbacks
const cleanup = triggerLoad(image, {
  onImageLoad: img => console.log('Loaded:', img.src),
  onImageError: (img, error) => console.error('Failed to load:', img, error),
})

// Later, cancel the load if it hasn't completed yet
cleanup()