Automatically add a progress bar to your site.

Overview

PACE

Latest Release Stars Forks License

An automatic web page progress bar.

Demo

Documentation

Include pace.js and the theme css of your choice on your page (as early as is possible), and you're done!

Pace will automatically monitor your ajax requests, event loop lag, document ready state, and elements on your page to decide the progress. On ajax navigation it will begin again!

If you use AMD or Browserify, require pace.js and call pace.start() as early in the loading process as is possible.

Example

<head>
  <script src="https://cdn.jsdelivr.net/npm/pace-js@latest/pace.min.js"></script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pace-js@latest/pace-theme-default.min.css">
</head>

Configuration

Pace is fully automatic, no configuration is necessary to get started.

If you would like to make some tweaks, here's how:

You can set window.paceOptions before bringing in the file:

paceOptions = {
  // Disable the 'elements' source
  elements: false,

  // Only show the progress on regular and ajax-y page navigation,
  // not every request
  restartOnRequestAfter: false
}

You can also put options on the script tag:

<script data-pace-options='{ "ajax": false }' src="https://cdn.jsdelivr.net/npm/pace-js@latest/pace.min.js"></script>

If you're using AMD or Browserify, you can pass your options to start:

define(['pace'], function(pace){
  pace.start({
    document: false
  });
});

Themes

Pace includes a bunch of themes to get you started. Just include the appropriate css file. Send us a PR with any interesting themes you create.

If you have minor styling changes and don't want to extend theme css, you can add custom class names to the progress bar using the "className" option:

paceOptions = {
  className: 'my-custom-class'
}

Collectors

Collectors are the bits of code which gather progress information. Pace includes four default collectors:

  • Ajax

    Monitors all ajax requests on the page

  • Elements

    Checks for the existance of specific elements on the page

  • Document

    Checks the document readyState

  • Event Lag

    Checks for event loop lag signaling that javascript is being executed

They can each be configured or disabled through configuration options of the same name.

paceOptions = {
  ajax: false, // disabled
  document: false, // disabled
  eventLag: false, // disabled
  elements: {
    selectors: ['.my-page']
  }
};

Add your own classes to paceOptions.extraSources to add more sources. Each source should either have a .progress property, or a .elements property which is a list of objects with .progress properties. Pace will automatically handle all scaling to make the progress changes look smooth to the user.

Elements

Elements being rendered to the screen is one way for us to decide that the page has been rendered. If you would like to use that source of information (not required at all), specify one or more selectors. You can comma separate the selectors to propertly handle error states, where the progress bar should disappear, but the element we are looking for may never appear:

paceOptions = {
  elements: {
    selectors: ['.timeline, .timeline-error', '.user-profile, .profile-error']
  }
}

Pace will consider the elements test successful when each selector matches something. For this example, when either .timeline or .timeline-error exist, and either .user-profile or .profile-error exist.

Restart Rules

Most users want the progress bar to automatically restart when a pushState event occurs (generally means ajax navigation is occuring). You can disable this:

paceOptions = {
  restartOnPushState: false
}

You can also have pace restart on every ajax request which lasts longer than x ms. You'll want to disable this if you make ajax requests the user doesn't need to know about, like precaching:

paceOptions = {
  restartOnRequestAfter: false
}

You can always trigger a restart manually by calling Pace.restart()

See the source for a full list of options.

API

Pace exposes the following methods:

  • Pace.start: Show the progress bar and start updating. Called automatically if you don't use AMD or CommonJS.

  • Pace.restart: Show the progress bar if it's hidden and start reporting the progress from scratch. Called automatically whenever pushState or replaceState is called by default.

  • Pace.stop: Hide the progress bar and stop updating it.

  • Pace.track: Explicitly track one or more requests, see Tracking below

  • Pace.ignore: Explicitly ignore one or more requests, see Tracking below

Events

Pace fires the following events:

  • start: When pace is initially started, or as a part of a restart
  • stop: When pace is manually stopped, or as a part of a restart
  • restart: When pace is restarted (manually, or by a new AJAX request)
  • done: When pace is finished
  • hide: When the pace is hidden (can be later than done, based on ghostTime and minTime)

You can bind onto events using the on, off and once methods:

  • Pace.on(event, handler, [context]): Call handler (optionally with context) when event is triggered
  • Pace.off(event, [handler]): Unbind the provided event and handler combination.
  • Pace.once(event, handler, [context]): Bind handler to the next (and only the next) incidence of event

Tracking

By default, Pace will show any ajax requests which begin as a part of a normal or ajax-y page load, or which last longer than 500ms.

You can disable all ajax tracking by setting ajax to false:

Pace.options = {
  ajax: false
}

You can disable ajax tracking except on page navigation by setting restartOnRequestAfter to false:

Pace.options = {
  restartOnRequestAfter: false
}

You can manually disable tracking for a specific request or requests by triggering them within a Pace.ignore callback:

Pace.ignore(function() {
  $.ajax(...)
});

You can force the progress bar to be shown for a specific request by triggering them within a Pace.track callback:

Pace.track(function() {
  $.ajax(...)
});

You can also ignore URLs based on a pattern:

Pace.options = {
  ajax: {
    ignoreURLs: ['some-substring', /some-regexp/]
  }
}

Dependencies

None!

Support

Pace is designed to support IE8+ (standards mode), FF 3.5+, Chrome, Safari 4+, Opera 10.5+, and all modern mobile browsers. If you run into a compatibility issue, or can make a case for supporting something else, please create an issue.

Size

pace.js is 4kb minified and gzipped. The themes vary between 0.5 and 4kb.

Issues

We have obviously not tested this on every website. If you run into an issue, or find a way the automatic detection could be better, please create an Issue. If you can include a test case, that's even better.

Credits

HubSpot

CodeByZach

Javascript by Zack Bloom CSS by Adam Schwartz

Themes inspired by Mary Lou

Project inspired by nprogress

Comments
  • ie8 stops at 98 or 99% and will not complete page load

    ie8 stops at 98 or 99% and will not complete page load

    Hi,

    I have this in production and IE8 users are experiencing a hang in the pace script at 99%. The page will eventually load for some, but not all ie8 users. Even when the page does completely load the pace loader bar is still on screen and at 99%. I have adjusted the lagThreshold: up to 10 from 3 but still not fixed. Any help would be appreciated. Example here: http://ohontherecord.org/dynamic-seiu-dues-graph/?id=258&form_id=7&graph=seiu

    Thanks!

    opened by f4d 28
  • AJAX Requests don't Trigger Pace

    AJAX Requests don't Trigger Pace

    I've just 'installed' Pace into my app and it works perfectly on the main page load but on any subsequent AJAX requests that occur after the initial page load the animation doesn't trigger when I believe Pace should handle these automatically?

    From reading the docs I think I can manually trigger and stop Pace by doing

    Pace.start // Pace.restart ?
    $.ajax({    
        success: function(data) {
            Pace.stop
        }
    });
    

    or even wrap the AJAX requests like so:

    Pace.track(function(){
        $.ajax(...)
    });
    

    but I have a load of requests throughout my app and trying to avoid having to go back and change them all.

    I've simply included Pace in my page like so

    <!-- pace.js -->
    <script type="text/javascript" src="/plugins/pace/pace.js"></script>
    <link href="/plugins/pace/pace.css" rel="stylesheet" type="text/css"/>
    

    with no options set etc.

    Should've mentioned I'm using jQuery but I've just read through all the previously closed issues and found the answer:

    $(document).ajaxStart(function() { Pace.restart(); });
    
    opened by martincarlin87 25
  • Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user's experience

    Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user's experience

    In Firefox 35.0.1 and Firefox 36 it works but I get the following warning in the console about pace.js line 434:

    Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user's experience. For more help http://xhr.spec.whatwg.org/

    Line 434 is:

    return _open.apply(req, arguments);

    This is on the latest version, pace 1.0.2, as well as previous versions I've tried.

    opened by primehalo 22
  • Including with Turbolinks breaks Turbolinks page refresh

    Including with Turbolinks breaks Turbolinks page refresh

    Without too much diagnoses, my current app works with Turbolinks, and each page only loads the body component as it should.

    Adding Pace to the site causes each navigation to fail and force a full page refresh:

    Uncaught Error pace.js?body=1:3 b pace.js?body=1:3 a.getElement pace.js?body=1:3 a.destroy pace.js?body=1:3 Pace.stop pace.js?body=1:3 Pace.restart pace.js?body=1:3 x pace.js?body=1:3 window.history.replaceState.window.history.replaceState pace.js?body=1:3 rememberCurrentUrl turbolinks.js?body=1:167 initializeTurbolinks turbolinks.js?body=1:381 (anonymous function) turbolinks.js?body=1:410 (anonymous function) turbolinks.js?body=1:422

    opened by jakcharlton 20
  • AngularJS support

    AngularJS support

    Hi,

    I try to use pace in one AngularJS application, it seems not work at all. It will freeze the browser or cause some Javascript error output to the console.

    opened by oliverzy 20
  • Ownership

    Ownership

    In @a2intl's pursuit of getting https://github.com/HubSpot/pace/pull/504 merged he reached out and mentioned @EatBreatheCode's fork as being active. We're clearly not. @eatbreathecode would you be interested in ownership of this project?

    opened by FranDias 16
  • Updating v1.0.2 to v.1.2.3 - Some Ajax calls not completing

    Updating v1.0.2 to v.1.2.3 - Some Ajax calls not completing

    Hi,

    I have been using v1.0.2 for some time, but started noticing issues with Firefox keeping Pace.js running even after the page has loaded. I know this has been recorded and should be fixed in v1.2.3.

    After upgrading to v1.2.3, I now see that some of my AJAX get calls are not working properly. The API gets hit and returns data, but I never get into the Ajax success or error. I can get it to fail consistently for some calls, but others to the same API work fine. So I wonder if it is larger datasets that are causing the issue?

    Rolling back to v1.0.2 and my AJAX calls are back working but the FF issue persists.

    My paceOptions:

    paceOptions = { ajax: { trackMethods: ['GET', 'POST', 'DELETE', 'PUT', 'PATCH'], ignoreURLs: ['mouseflow', 'mainHub', '__browserLink', 'browserLinkSignalR', 'ServiceBusTopicHub', 'signalr'], trackWebSockets: false } }

    In the below code, it sometimes never enters the success or error when using v1.2.3, but always works using v1.0.2

    $.ajax({
            url: getAbsoluteUrl(' / ') + "api/AdminSections?vesselid=" + Vessel.ID,
            type: 'GET',
            dataType: 'json',
            success: function (folios) {
                console.log("Success");
                console.log(folios);
            },
            error: function (request, message, error) {
                console.error(message);
                handleException(request, message, error);
            }
        });
    
    opened by euangordon 15
  • Doesn't work with Backbone

    Doesn't work with Backbone

    Hello,

    it seems that the plugin doesn't detect Backbone's ajax requests, as I'm trying to use it on a Backbone app and it doesn't appear (apart from the dom first load)

    Any advice about how to fix it?

    Thanks

    opened by squallstar 15
  • Not loading the full width of page

    Not loading the full width of page

    My Example: http://yoyo.io/css/

    I have successfully integrated Pace to Wordpress using the http://roots.io theme I get the same behaviour as your demo in which the progress from left to right falls short early - about 75-80% width of the page.

    Yours is perfect: http://github.hubspot.com/pace/docs/welcome/

    Mine is not: http://yoyo.io/css/

    The css used is your minimal theme:

    .pace .pace-progress {
      background: #29d;
      position: fixed;
      z-index: 2000;
      top: 0;
      left: 0;
      height: 2px;
    
      -webkit-transition: width 1s;
      -moz-transition: width 1s;
      -o-transition: width 1s;
      transition: width 1s;
    }
    
    .pace-inactive {
      display: none;
    }
    
    opened by shaneholloman 13
  • Websocket support

    Websocket support

    Go to http://www.websocket.org/echo.html , open network inspector (in Chrome/Safari/Opera) and then hit "Connect". You'll see that a pending "Switching boards 101" will be pending forever. This will cause pace to not hide in a single-page webpage with websockets.

    opened by alexandernst 13
  • [Feature] Method to completely unload Pace

    [Feature] Method to completely unload Pace

    I want the pace progress bar to be seen only once in my single page app. And never again afterwards. So, I tried something like:

                Pace.once('done', function() {
                    Pace.stop();
                    Pace = null;
                })
    

    But Pace = null will cause a crash because a callback (timeout) is still running.

    Also, I want to be able to completely unload pace from memory when I do not need it anymore.

    Thanks!

    opened by binarykitchen 11
  • No way to start loading besides ajax requests?

    No way to start loading besides ajax requests?

    is there any way to start pace loading besides ajax requests?, from what've seen in the docs it only detects ajax requests and not normal ones, and you can't even start it manually only fire events...

    opened by sacalata 0
  • module not defined

    module not defined

    It seems that when you have an object called "exports" defined, pace.js tries to set a property on a module. In my case module does not exist, so there's a console error.

    I think that line 978: https://github.com/CodeByZach/pace/blob/2350e563a7c899deb2b93903bee7164921018b2b/pace.js#L978-L980

    should be changed to typeof module since that appears to be the purpose anyways (set the property "exports" on the object "module")

    Am I missing something here?

    Thanks!

    opened by j-applese3d 0
  • Angular's ApplicationRef never fire

    Angular's ApplicationRef never fire "isStable = true" in Firefox because of pace-js

    Hi,

    OK, it's a weird one, granted, but I'm at a loss... :/

    Description

    In Firefox, simply adding pace-js to the application causes Angular to never fire the ApplicationRef.isStable = true event. But, in Chrome, Edge, Brave, it fires like expected...

    Reproduction

    1. Install the Angular CLI
    2. Create a new clean Angular app: ng new testapp
    3. Add the following in app.component.ts:
      constructor(appRef: ApplicationRef) {
          appRef.isStable
            .pipe(
              tap((isStable) => console.log('stable', isStable)),
              first((isStable) => isStable),
              take(1)
            )
            .subscribe(() => {
              console.log('******** Application is stable **********');
            });
        }
      
    4. Run ng serve and confirm the output (in Firefox)

    [webpack-dev-server] Live Reloading enabled. stable false Angular is running in development mode. Call enableProdMode() to enable production mode. stable true ******** Application is stable **********

    1. Add pace-js to the appliation: run ng add pace-js
    2. Modify angular.json to include the pace-js script:
              "scripts": [
                "node_modules/pace-js/pace.min.js"
              ]
      
    3. Run ng serve again and confirm the output (in Firefox)

    [webpack-dev-server] Live Reloading enabled. stable false Angular is running in development mode. Call enableProdMode() to enable production mode.

    Problem: The application never become "stable"! In Chrome and Edge, the isStable = true "event" is fired as expected.

    The Angular doc about ApplicationRef says:

    the application will never be stable if you start any kind of recurrent asynchronous task when the application starts (for example for a polling process, started with a setInterval, a setTimeout or using RxJS operators like interval);

    I know the pace-js source code has setInterval and setTimeout in it, so it's probably related somehow, I don't know. Any ideas how to resolve this? And why only Firefox seems affected?

    Tested with:

    • Angular v13.3.0
    • Firefox v105.0.1 (64-bit)
    • pace-js v1.2.4
    opened by dstj 2
  • Fix a bug when there's an error when starting or destroying the bar

    Fix a bug when there's an error when starting or destroying the bar

    Presumably this is incredibly unlikely to happen as I couldn't see any issues about this, and it's a bug that has been around for a very long time.

    There's an error class that gets defined, NoTargetError, that inherits from Error and is used in Bar.prototype.getElement when the target element doesn't exist in the DOM. However, there's a couple of places in the code where NoTargetError gets redefined inside of catch {} blocks, and assigned to the error instance instead. Later, if the code tries to throw new NoTargetError again, it'll fail because the error instance is not a constructor.

    I looked back at an older version of the repo to find the original Coffeescript source file: https://github.com/CodeByZach/pace/blob/v1.2.0/pace.coffee. I believe that the error handling in this file was just poorly written - they've used catch NoTargetError, and I believe the intention here is that only NoTargetError errors should be caught. But the resulting compiled javascript code is:

    catch (_error) {
      NoTargetError = _error;
    }
    

    I've re-written those catch blocks as:

    catch (_error) {
      // This is ok
    }
    

    This means that all errors, including NoTargetError, will get caught and suppressed - the same behaviour as before. But the code no longer reassigns NoTargetError.

    The original commit introducing NoTargetError and the catch block is here: https://github.com/CodeByZach/pace/commit/db587611564d06ee8218d9b63567eec121cc0642

    opened by 6twenty 1
  • Issue with the pace bar not stopping

    Issue with the pace bar not stopping

    I have a new project asp.net core 6 MVC, I added the pace js and css. But when the page loads the pace bar never completes and goes away.

    I have tried in edge, chrome, and safari. Any suggestions to the issue?

    If I use the old version 0.5.6 the pace bar goes away.

    opened by glconsultingservice 2
  • Display loading pace only if it takes more than 3 seconds to load?

    Display loading pace only if it takes more than 3 seconds to load?

    How can I display the loading pace only if it takes more than 3 seconds to load? Does anyone know how to do this? I didn't manage to find out how to do it.

    opened by thainapires 1
Releases(v1.2.4)
ProgressJs is a JavaScript and CSS3 library which help developers to create and manage progress bar for every objects on the page.

ProgressJS ProgressJs is a JavaScript and CSS3 library which helps developers create and manage progress bars for every object on the page. How To Use

usablica 2.4k Dec 30, 2022
Responsive and slick progress bars

ProgressBar.js Responsive and slick progress bars with animated SVG paths. Use built-in shapes or create your own paths. Customize the animations as y

Kimmo Brunfeldt 7.7k Jan 8, 2023
Very lightweight progress bars. No jQuery

Very lightweight progress bars (~699 bytes gzipped). Compatibility: iE7+ and the rest of the world Demo See nanobar.jacoborus.codes Installation Downl

Jacobo Tabernero 2.9k Dec 19, 2022
Material Progress —Google Material Design Progress linear bar. By using CSS3 and vanilla JavaScript.

MProgress.js Google Material Design Progress Linear bar. It uses CSS3 and vanilla JavaScript which doesn't depend on any other libraries. Types and pr

gc 1.5k Nov 30, 2022
This plugin for Chart.js that makes your bar chart to 100% stacked bar chart.

chartjs-plugin-stacked100 This plugin for Chart.js that makes your bar chart to 100% stacked bar chart. Requires Chart.js 3.x. Demo: https://y-takey.g

y-take 106 Jan 3, 2023
ProgressJs is a JavaScript and CSS3 library which help developers to create and manage progress bar for every objects on the page.

ProgressJS ProgressJs is a JavaScript and CSS3 library which helps developers create and manage progress bars for every object on the page. How To Use

usablica 2.4k Dec 30, 2022
Creates a button that turns into a progress bar with a elastic effect. Based on the Dribbble shot "Download" by xjw

Elastic Progress Creates a button that turns into a progress bar with a elastic effect. Based on a Dribbble shot by xjw. By Lucas Bebber. Article on C

Codrops 876 Jan 1, 2023
Multi Upload with Progress Bar in Vanilla JS

js-progress-bar-multi-upload Multi Upload with Progress Bar in Vanilla JS Youtube dersinde birlikte hazırladığımız çoklu progress barlı javascript upl

Tayfun Erbilen 11 Jun 10, 2022
CLI Progress Bar implemented in NodeJS to track Time, ETA and Steps for any long running jobs in any loops in JS, NodeJS code

NodeJS-ProgressBar CLI Progress Bar for NodeJS and JavaScript to track Time, ETA and Steps for any long running jobs in any loops in JS, NodeJS code D

Atanu Sarkar 5 Nov 14, 2022
A progress bar plugin for Vite.

vite-plugin-progress Display with progress bar when building ?? Install npm i vite-plugin-progress -D # yarn yarn add vite-plugin-progress -D # pn

Jeddy Gong 137 Dec 17, 2022
A progress bar plugin for tasks in Obsidian.

Obsidian Task Progress Bar A plugin for showing task progress bar near the tasks bullet or headings. Only works in Live Preview mode in Obsidian. Sett

Boninall 52 Dec 31, 2022
Super lighweight, pure JavaScript page load progress bar

Nanobar Super lighweight, pure JavaScript page load progress bar Status View Preview Table of contents Status Quick Start What's included Bugs and fea

The MUDA Organization 5 Jan 3, 2022
A set of flat and 3D progress button styles where the button itself serves as a progress indicator

A set of flat and 3D progress button styles where the button itself serves as a progress indicator. 3D styles are used for showing the progress indication on one side of the button while rotating the button in perspective.

Codrops 608 Oct 19, 2022
Bookstore CMS React Front-End to display a list of books, categorize it, add and remove books and update your reading progress

Bookstore REACT app to manage your books Build an app to display a list of books, categorize it, add and remove books and update your reading progress

Eapen Zacharias 3 Aug 19, 2022
null 8 Nov 11, 2022
A student-made, student-tailored Firefox add-on for Veracross. Provides ease of navigation in Veracross, among with other quality of life features. More features in progress.

Check out the Chrome version! This release is version 1.0.0, so the only feature it has is clickable links to the dropbox from the classpage. Any comm

Webb School CS Club 3 Nov 25, 2022
A crawler that crawls the site's internal links, fetching information of interest to any SEO specialist to perform appropriate analysis on the site.

Overview ?? It is a module that crawls sites and extracts basic information on any web page of interest to site owners in general, and SEO specialists

Yazan Zoghbi 2 Apr 22, 2022
A crawler that crawls the site's internal links, fetching information of interest to any SEO specialist to perform appropriate analysis on the site.

Overview ?? It is a module that crawls sites and extracts basic information on any web page of interest to site owners in general, and SEO specialists

Yazan Zoghbi 2 Apr 22, 2022
An app to test out your typing speed, save your progress and view statistics against them.

Introduction An app to test out your typing speed, save your progress and view statistics against them. Demo Check out the quick demo here. Getting St

Nithin Kumar B 2 Sep 7, 2022