Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Progressio transforms your static website to a dynamic environment. Pages are loaded asynchronously, with the use of the browser history JavaScript API and a beautiful overlay progress bar.

This library was originally built for Waaave - you can test it live there.

Progressio is published under the terms of the Mozilla Public License v2.0 (MPL v2.0) license - see the file.

Testing Progressio

You can test Progressio by opening page: ./examples/simple_1.html.

Note: You first need to build Progressio, please refer to the Installation Notes section of this document.

Installation Notes


Progressio depends on the following libraries:


Progressio can be built using the GruntJS build system.

Execute one of the following commands to build the library:

  • grunt build

Once done, you can retrieve the progressio.js and progressio.css files in the build/ folder.


Using Progressio is straightforward. Find out how to use it below.

1. Include library files

Load Progressio source files and its dependencies in the head of your website pages. Please add it globally to your website (in your base template - provided you're using a template system).

<!-- BEGIN Dependencies -->
<script src="./build/javascripts/libs.min.js" type="text/javascript" data-progressio-scope="common"></script>
<!-- END Dependencies -->

<!-- BEGIN Progressio -->
<script src="./build/javascripts/progressio.min.js" type="text/javascript" data-progressio-scope="common"></script>
<link rel="stylesheet" href="./build/javascripts/progressio.min.css" type="text/css" data-progressio-scope="common">
<!-- END Progressio -->

2. Initiliaze library configuration

Progressio needs to be initialized in order to apply its change.

Once the library is loaded (on document ready, typically), execute the following snippet:

(new Progressio({
  /* {blue|red|green|yellow|orange|black|purple|(custom)} */
  /* Default: 'blue' */
  color: 'blue',

  /* [optional] Fix position of the loading bar (always visible on top, even when scrolling down) */
  /* Default: false */
  fixed: false,

  /* [optional] Loading bar location {top|bottom} - requires 'fixed' set to true */
  /* Default: 'top' */
  location: 'top',

  /* [optional] Site-wide page container */
  /* Default: '#body' */
  container: '#body',

  /* [optional] Where to insert the load bar? */
  /* Default: 'body' */
  load_bar: 'body',

  /* [optional] Auto-hide bar when page load is done? */
  /* Default: false */
  auto_hide: false,

  /* [optional] Event callbacks */
  callbacks: {
    post_display: {
      before: function() {},
      after: function() {}

    on_complete: {
      before: function() {},
      after: function() {}

  /* [optional] Console wrapper (native console or Console.js) */
  console: Console,

Note: Progressio is configurable, refer to the comments above each line for available values.

3. Tag links to be excluded

By default, Progressio patches all local links (links with the same domain and protocol as the current page being browsed + relative and absolute links without the host part).

If, for any reason, you want a link not to be patched, add the data-progressio-async="disabled" tag to the link element, as below:

<a href="/path/to/other/page/" data-progressio-async="disabled">Path To Other Page</a>

Note: links with target="_blank" are not patched, in any case.

4. Tag common dependencies (stylesheets + scripts)

Progressio processes an automated diff of the page head dependencies while browsing.

It automatically includes and load new CSS stylesheets and JS scripts. If your website has site-wide/common dependencies, you may want to add a tag to let Progressio know it shouldn't replace it.

Set its Progressio scope to "common" by adding the data-progressio-scope="common" tag to the script/link element, as below:

<!-- This script WON'T BE replaced -->
<script src="/not/to/replace.js" type="text/javascript" data-progressio-scope="common"></script>

<!-- This stylesheet WON'T BE replaced -->
<link rel="stylesheet" href="/not/to/replace.css" type="text/css" data-progressio-scope="common">

<!-- This stylesheet WILL BE replaced -->
<link rel="stylesheet" href="/can/be/replaced.css" type="text/css">


🎈 Beautiful & stylish asynchronous page loader. Makes a static website dynamic in a breeze.







No packages published