Guide · Open source
How to use Pace: add a progress bar to your web page
Updated · written with AI from the project's own documentation and checked against our catalogue data
Pace is a small JavaScript file that shows a progress bar at the top of a web page while it loads. This guide shows you how to add it with two tags in your page head, pick a theme, and adjust its behaviour when you need to. It is written for website owners and front-end developers who want visitors to see that a page is still loading.
PaceCodeByZach/pace · ★ 15.6k · MIT Install options & downloads Quick start
- 1Add the script. Place the pace.min.js script tag in your page head, as early as possible.
- 2Add a theme. Place the theme stylesheet link in your page head. Pick a theme from the Pace demo.
- 3Load your page. Open the page in a browser. The progress bar should show at the top while the page loads.
- 4Test ajax navigation. If your site changes pages with ajax or pushState, check that the bar restarts on each change.
- 5Adjust options if needed. Set window.paceOptions before the script to disable sources or change restart rules.
- 6Review the documentation. Read the full list of options in the Pace documentation or the source file for details.
What Pace does and when it helps
Pace watches ajax requests, the document ready state, event loop lag, and elements on the page to estimate progress. In most cases you do not need to write any code for it to work.
It is most useful for letting visitors know that a page is still loading, including on ajax-heavy pages where the browser does not show its own loading indicator.
Add Pace to your page
Include pace.js and a theme stylesheet in your page head, as early as possible. The README says that is all you need to do to get started.
The README example uses the jsDelivr CDN links shown below.
- Add the script to the head of your page.
- Add a theme stylesheet to the head of your page.
- Load the page and the progress bar will appear while it loads.
<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>Choose a theme
Pace includes several ready-made themes. To use one, include its CSS file. The default theme is shown in the example above.
If you only need small styling changes, you can add your own class name to the progress bar with the className option instead of extending a theme.
- Include the theme CSS file that matches the look you want.
- Use the className option to add a custom class for minor tweaks.
paceOptions = {
className: 'my-custom-class'
}Configure Pace (optional)
Pace is fully automatic, so configuration is optional. To make changes, set window.paceOptions before you include the file. You can also put options on the script tag as a JSON string in the data-pace-options attribute.
Each collector (ajax, elements, document, eventLag) can be configured or disabled through an option of the same name.
- elements: false disables the elements source.
- restartOnRequestAfter: false shows progress only on regular and ajax-style page navigation, not every request.
- restartOnPushState: false turns off the automatic restart on pushState events.
paceOptions = {
// Disable the 'elements' source
elements: false,
// Only show the progress on regular and ajax-y page navigation,
// not every request
restartOnRequestAfter: false
}Control tracking and restarts in code
Pace exposes methods for manual control. Pace.restart() triggers a restart at any time. Pace.ignore and Pace.track let you exclude or force-show specific requests.
You can also ignore URLs matching a substring or regular expression through the ajax ignoreURLs option.
- Pace.start shows the bar and starts updating.
- Pace.restart shows the bar if hidden and starts again from zero.
- Pace.stop hides the bar and stops updating.
- Pace.on, Pace.off and Pace.once bind to events such as start, stop, restart, done and hide.
Pace.ignore(function() {
$.ajax(...)
});Use Pace with AMD or Browserify
If you use AMD or Browserify, require pace.js and call pace.start() as early in the loading process as possible. Pass options to start if you need them.
define(['pace'], function(pace){
pace.start({
document: false
});
});What people use it for
- Showing a loading bar on a site that has no custom loading code.
- Adding feedback to a single-page app or ajax-heavy page.
- Restarting the bar on each ajax navigation step.
- Picking a ready-made progress bar style that fits an existing design.
Frequently asked questions
How do I install Pace?
Include the pace.min.js script and a theme stylesheet in your page head, as early as possible. The README gives these jsDelivr CDN links as the basic setup. No other install step is listed.
Is Pace free to use?
Pace is released under the MIT licence, as stated in the project information. Check the LICENSE file in the repository for the full terms.
Does Pace need any requirements or dependencies?
The README lists no prerequisites and says Dependencies: None. Pace runs in the browser, so the page must run JavaScript.
Does Pace work on server-rendered pages without JavaScript?
No. Pace depends on running in the browser, so it will not show a bar on a page where scripts do not run.
Can I control the progress values myself?
Pace decides progress automatically according to the README. You can add your own sources through paceOptions.extraSources, but fine-grained manual progress control is not the design goal.
What is an alternative to Pace?
NProgress is a comparable project. The Pace README notes that it was inspired by nprogress.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Pace suits website owners and front-end developers who want an automatic loading bar with almost no code, especially on ajax navigation sites. If you need precise manual control over progress, or a loading indicator for a page that runs without JavaScript, pick a different tool such as a server-side indicator or a library with explicit progress control.
Install options & downloads