Skip to main content

ProgressPreloader

Page preloader for tracking and displaying the loading progress of resources (images, videos, custom elements).

  • Takes images and videos into account
  • Supports virtual resources
  • Calculates smooth loading progress for better animations.

Basic Demo​

More demos​

To explore more demos, click here.

Features​

  • Smooth progress calculation based on observed loading state.
  • Custom resource weight.
  • Virtual resources for manual or async progress control.

Initialization​

caution

The module does not provide styling for the container.

<div id="preloader">
  <div id="progress">00%</div>
</div>
#preloader {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 9;

  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}
import { ProgressPreloader } from "vevet";

const preloader = new ProgressPreloader(
  {
    container: document.getElementById("preloader"),
    hide: 700
  },
  {
    onProgress: () => {
      const { progress } = preloader;
      const percent = clamp(progress * 100, 0, 99);
      const html = `${percent.toFixed(0)}%`;

      progressElement.innerHTML = html;
    }
  }
);

Add a custom resource:

<div class="js-preload" data-weight="10"></div>

<!-- Update its 'loaded' attribute -->
<div class="js-preload" data-weight="10" data-loaded="7"></div>

Add a virtual resource:

preloader.addResource('my-resource', 20);
preloader.resolveResource('my-resource', 15);

Destroy the preloader:

preloader.destroy();

Best Practices​

  • The preloader does not perform resource loading — it only tracks loading progress.
  • Preloading lazy images is not supported — they are ignored automatically.
  • Avoid assigning extremely high resource weight values; balanced weights create smoother progress.
  • Virtual resources are ideal for async operations (API, WebGL, timers).
  • Use lerp < 1 for cinematic UI preloaders; use lerp: 1 for strict "technical" progress indicators.
  • Avoid triggering destroy() before the preloader reaches loadProgress = 1, unless you intend to cancel preloading completely.