An automatic web page progress bar.
Include pace.js and the theme css of your choice on your page (as early as 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 possible.
<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>
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
});
});
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 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 existence 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 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