browser-preloader

Preload resources in browser, e.g: images.

Install

npm install browser-preloader

yarn add browser-preloader

pnpm add browser-preloader

Usage

import { preloadImages } from 'browser-preloader'

// Basic usage
const loadedImages = await preloadImages(['foo.jpg', 'bar.png'])
console.log(`Loaded ${loadedImages.length} images`)

// With callbacks
preloadImages(['foo.jpg', 'bar.png'], {
  timeout: 5000,
  onProgress(loaded, total) {
    console.log(`Progress: ${loaded}/${total}`)
  },
  onComplete(images) {
    console.log(`Successfully loaded: ${images.length}`)
  },
  onError(err, url) {
    console.log(`Image ${url} failed to load`, err)
  },
})

// Load images when browser is idle
preloadImages(['foo.jpg', 'bar.png'], {
  loadOnIdle: true,
  idleTimeout: 2000,
})

// Sequential loading with limited concurrency
preloadImages(['foo.jpg', 'bar.png', 'baz.jpg'], {
  strategy: 'sequential',
  maxConcurrent: 2,
})

// With cross-origin support
preloadImages(['https://example.com/image.jpg'], {
  crossOrigin: true,
  crossOriginAttribute: 'anonymous',
})

API

preloadImages

• Type: (images: string | string[], options: PreloadImagesOptions = {}) => Promise<HTMLImageElement[]>

Preload images in browser.

Parameters

images

• Type: string | string[]

Array of image URLs or a single image URL.

options

• Type: PreloadImagesOptions
• Required: false

Options for preloading images, see PreloadImagesOptions in Interfaces.

Interfaces

/**
 * Options for the {@link preloadImages} function
 */
export interface PreloadImagesOptions {
  /**
   * Whether to set the cross-origin attribute on the image
   *
   * @default false
   */
  crossOrigin?: boolean

  /**
   * The cross-origin attribute to use for the image
   *
   * @default `anonymous`
   */
  crossOriginAttribute?: 'anonymous' | 'use-credentials'

  /**
   * Timeout for requestIdleCallback in milliseconds
   * Only effective when loadOnIdle is true
   *
   * @default 2000
   */
  idleTimeout?: number

  /**
   * Whether to load images only when browser is idle
   * Uses requestIdleCallback API if available
   *
   * @default false
   */
  loadOnIdle?: boolean

  /**
   * Maximum number of concurrent image loads
   *
   * @default 6
   */
  maxConcurrent?: number

  /**
   * The strategy to load images
   *
   * @default `parallel`
   */
  strategy?: 'parallel' | 'sequential'

  /**
   * Timeout for image loading in milliseconds
   *
   * @default 0
   */
  timeout?: number

  /**
   * Callback function to be called when all images are loaded
   * @param loadedImages - Array of loaded HTMLImageElement objects
   */
  onComplete?: (loadedImages: HTMLImageElement[]) => void

  /**
   * Callback function to be called when an error occurs
   * @param error - Error object
   * @param url - The URL of the image that failed to load
   */
  onError?: (error: Error, url: string) => void

  /**
   * Callback function to be called when the progress of image loading changes
   *
   * @param loadedCount - Number of images loaded so far
   * @param totalCount - Total number of images to be loaded
   */
  onProgress?: (loadedCount: number, totalCount: number) => void
}

License

MIT License © 2025-PRESENT ntnyq