ProgressPreloader

Page preloader for calculating and displaying the loading progress of resources (images, videos, custom elements). Provides smooth progress transitions.

Example

Explore a live example in CodePen:

Props

note

All Preloader's props are available in this class.

Static Props

Static properties are set during initialization and cannot be modified later.

Name	Description	Type	Default Value
preloadImages	Enables automatic preloading of images.	boolean	true
preloadVideos	Enables automatic preloading of videos.	boolean	false
customSelector	Selector for custom resources to preload. The elements should include data-weight and data-loaded attributes. Example: data-weight="10" to indicate a weight of 10 and data-loaded="10" when fully loaded.	string	'.js-preload'
ignoreClassName	Class name for elements to exclude from preloading.	string	'js-preload-ignore'
lerp	Linear interpolation factor for smooth progress updates. 1 disables interpolation for instant updates.	number	0.1
endDuration	Duration (ms) to complete the preloader if resources are loaded but the progress is still below 1.	number	500

Accessors

note

All Preloader's accessors are available in this class.

loadedWeight

Type: number

Loaded weight.

loadProgress

Type: number

Current loading progress (0 to 1).

progress

Type: number

Gets the current interpolated progress value (0 to 1).

resources

Type: IProgressPreloaderResource[]

The list of custom resources to preload.

IPointersItem Structure

interface IProgressPreloaderResource {
  id: string | Element;
  loaded: number;
  weight: number;
}

• id: The custom resource identifier.
• weight: A resource may be split into multiple parts. This is the resource weight
• loaded: Loaded weight

totalWeight

Type: number

Calculates the total number of resources to preload, including their weight.

Methods

note

All Preloader's methods are available in this class.

addResource

Adds a custom resource.

// preload a custom html element with its weight `100`
// the element itself may have the attributes: `data-weight` and `data-loaded`
instance.addResource(document.getElementById('preload-me'), 100);

// add a custom resource without an element
instance.addResource('my-resource', 20);

resolveResource

Emits a resource load event and updates the count of loaded resources.

// the resource's loaded weight is 19
instance.resolveResource('my-resource', 20);

Callbacks

note

All Preloader's callbacks are available in this class.

progress

Fired when the preloader's progress updates.

const destruct = instance.on('progress', () => console.log('progress update'));

// Cancel the callback
destruct();

resource

Fired each time a resource is loaded during preloading.

const destruct = instance.on('resource', ({ id, weight, loaded }) => {
  console.log(id, `loaded ${loaded} / ${weight}`);
});

// Cancel the callback
destruct();