Add a Loading Screen

Learn how to improve perceived performance by adding a loading screen to your site with Preloader

What is the Preloader?

Think of the preloader as a loading screen. The preloader is a small set of HTML, CSS, and JavaScript that is injected by the Adaptive.js boot loader before your adaptation is loaded by the browser. The preloader improves the perceived performance of your site by decreasing the amount of time a blank page is displayed on screen (i.e. the "white flash").

Adaptive.js 2.1 Adaptive.js Preloader requires Adaptive.js 2.1 or newer. See Upgrading to Adaptive v2.1 for more information.

Preloader Guidelines

The file size of the adaptive.min.js boot loader (which includes the preloader) is far more important than the file size of your adaptation (adaptation.min.js), since it is the first thing the user downloads before seeing anything on the page, while adaptation.min.js is downloading in the background. Keep it's size below 15 KB.

Any additional network requests made by the preloader will cause load delays. Instead of embedding <img> elements in your HTML (which would make a separate network request for the image) try an embedded SVG or minifying/base64 encoding the image file and embedding that in your HTML or CSS.

Preloader Source Files

There are a set of three files that make up the Preloader feature of the Adaptive.js framework, which you can find inside your Adaptive.js 2.1 project as:

Projects created with the Adaptive.js Generator have a boilerplate preloader to give you an idea of how it works. Feel free to modify it as you see fit.


The structure of your preloader is defined inside preload.html. Unlike the view templates you have been using with your Adaptive.js project, Dust.js templating is not available within the preloader, keeping file size to a minimum. This helps us keep the total size of the preloader small.


The styling of your preloader is defined inside preload.css. If you have enabled Sass in your project, note that the preloader uses standard CSS syntax and is not run through the Sass preprocessor.


Any functionality of your preloader should be defined inside preload.js. Use this file to perform tasks like sending analytics or user monitoring, etc.

It is recommended that you keep complexity low, because your script will block the browser from displaying your adapted page while it is being executed. The preloader JS is run before your project bundle is loaded, so you will not have access to a selector library like jQuery or Zepto at this stage.

Edit in GitHub