### NPM/CommonJS/AMD Installation and Start
Source: https://context7.com/codebyzach/pace/llms.txt
Install Pace.js via npm and call Pace.start() as early as possible in your module entry point. For AMD, use the define function.
```javascript
// npm install pace-js
const Pace = require('pace-js');
// Must be called before the page finishes loading for best results
Pace.start();
// AMD
define(['pace'], function(Pace) {
Pace.start({ document: false }); // disable document readyState monitoring
});
```
--------------------------------
### Basic HTML Setup with Pace.js
Source: https://context7.com/codebyzach/pace/llms.txt
Include pace.js and a theme CSS file as early as possible in the of your HTML document for automatic progress bar display.
```html
My App
```
--------------------------------
### Manual Pace.start() with Options
Source: https://context7.com/codebyzach/pace/llms.txt
Manually start Pace.js, which is useful in AMD/CommonJS environments. You can also provide an options object to override the current configuration for that specific start call.
```javascript
// Manual start — useful in AMD/CommonJS environments
Pace.start();
// Start with inline option overrides (merged into existing options)
Pace.start({
document: false,
ajax: {
trackMethods: ['GET', 'POST', 'PUT'],
ignoreURLs: ['/api/ping']
}
});
// Pace.running will be true while the bar is active
console.log(Pace.running); // true
```
--------------------------------
### AMD Integration for Pace.js
Source: https://context7.com/codebyzach/pace/llms.txt
Configure Pace.js using AMD's `require.config` and start it with custom AJAX tracking and router integration.
```javascript
require.config({
paths: { pace: 'https://cdn.jsdelivr.net/npm/pace-js@latest/pace.min' }
});
require(['pace'], function(Pace) {
// Start as early as possible
Pace.start({
ajax: { trackMethods: ['GET', 'POST'] },
restartOnPushState: false // handled by the router below
});
Pace.on('done', function() {
console.log('Initial load complete');
});
// Integrate with your router
myRouter.on('routeChange', function() {
Pace.restart();
});
});
```
--------------------------------
### Include Pace.js themes
Source: https://context7.com/codebyzach/pace/llms.txt
Include any theme CSS file after pace.js to apply styling. CDN examples are provided for various themes. Custom color and height overrides are possible using CSS variables or direct rule overrides.
```html
```
--------------------------------
### Pace.js Event System
Source: https://context7.com/codebyzach/pace/llms.txt
Bind handlers to Pace lifecycle events like 'start', 'stop', 'restart', 'done', 'hide', 'progress', and 'change'. Use 'once' for one-time handlers and 'off' to remove them. Fires 'progress' on every render tick.
```javascript
// Log every lifecycle event
Pace.on('start', function() { console.log('Pace started'); });
Pace.on('restart', function() { console.log('Pace restarted (SPA nav or new request)'); });
Pace.on('done', function() { console.log('Progress reached 100%'); });
Pace.on('hide', function() { console.log('Bar hidden (after ghostTime)'); });
Pace.on('stop', function() { console.log('Pace stopped manually'); });
// React to progress value changes (fires on every render tick)
Pace.on('progress', function(progress) {
document.title = Math.round(progress) + '% loaded';
});
// One-time handler — fires only on the first 'done' event
Pace.once('done', function() {
console.log('First load complete — removing splash screen');
document.getElementById('splash').style.display = 'none';
});
// Remove a specific handler
function onDone() { console.log('done'); }
Pace.on('done', onDone);
Pace.off('done', onDone);
// Remove ALL handlers for an event
Pace.off('progress');
```
--------------------------------
### Custom Pace.js class name
Source: https://context7.com/codebyzach/pace/llms.txt
Use the `className` option to namespace Pace's progress element, enabling multiple Pace instances or per-page styling without conflicts. Example shows targeting a custom class name with CSS.
```javascript
window.paceOptions = {
className: 'checkout-progress'
};
```
```css
/* Target only this page's Pace bar */
.pace .pace-progress.checkout-progress {
background: linear-gradient(to right, #f7971e, #ffd200);
height: 5px;
}
```
--------------------------------
### Pace.start([options])
Source: https://context7.com/codebyzach/pace/llms.txt
Renders the progress bar and begins monitoring all active sources. It can be called manually, especially in AMD/CommonJS environments, or with optional configuration overrides.
```APIDOC
## Pace.start([options])
Renders the progress bar and begins monitoring all active sources. Called automatically on page load unless using AMD/CommonJS. Accepts an optional options object to override the current configuration.
### Method
JavaScript
### Parameters
#### Options (Optional)
- **document** (boolean) - Whether to monitor document.readyState.
- **ajax** (object) - Configuration for AJAX monitoring.
- **trackMethods** (array of strings) - HTTP methods to monitor (e.g., ['GET', 'POST']).
- **trackWebSockets** (boolean) - Whether to track WebSocket connections.
- **ignoreURLs** (array of strings or regexps) - URLs to ignore for tracking.
- **elements** (object) - Configuration for monitoring specific DOM elements.
- **checkInterval** (number) - Interval in ms to check for elements.
- **selectors** (array of strings) - CSS selectors for elements to monitor.
- **minTime** (number) - Minimum time in ms the bar is shown.
- **ghostTime** (number) - Time in ms the bar lingers after hitting 100%.
- **restartOnRequestAfter** (number or boolean) - Time in ms after which to restart the bar on requests, or false to only restart on navigation.
- **restartOnPushState** (boolean) - Whether to restart the bar on pushState / replaceState.
- **eventLag** (boolean or number) - Whether to disable event-loop lag monitoring or set a threshold.
### Request Example
```javascript
// Manual start
Pace.start();
// Start with inline option overrides
Pace.start({
document: false,
ajax: {
trackMethods: ['GET', 'POST', 'PUT'],
ignoreURLs: ['/api/ping']
}
});
```
### Response
- **Pace.running** (boolean) - Indicates if the progress bar is currently active.
```
--------------------------------
### Configure Pace.js with AMD/Browserify
Source: https://github.com/codebyzach/pace/blob/master/README.md
When using AMD or Browserify, pass configuration options to the `pace.start()` method after requiring the pace module.
```javascript
define(['pace'], function(pace){
pace.start({
document: false
});
});
```
--------------------------------
### Pace.start
Source: https://github.com/codebyzach/pace/blob/master/README.md
Shows the progress bar and begins updating its progress. This is called automatically if you are not using AMD or CommonJS module systems.
```APIDOC
## Pace.start
### Description
Shows the progress bar and starts updating.
### Method
`Pace.start()`
### Parameters
None
### Request Example
```javascript
Pace.start();
```
### Response
None
```
--------------------------------
### Inline Configuration via data-pace-options
Source: https://context7.com/codebyzach/pace/llms.txt
Pass JSON options directly on the script tag using the data-pace-options attribute for inline configuration without needing a global variable.
```html
```
--------------------------------
### Include Pace.js and Theme
Source: https://github.com/codebyzach/pace/blob/master/README.md
Include the Pace.js script and a theme CSS file in the head of your HTML document as early as possible for automatic progress monitoring.
```html
```
--------------------------------
### Extra Sources (`paceOptions.extraSources`)
Source: https://context7.com/codebyzach/pace/llms.txt
Allows registering custom progress sources by providing classes with a `.progress` property. Pace scales these sources into a unified progress value.
```APIDOC
## Extra Sources (`paceOptions.extraSources`)
Register custom progress sources by providing classes with a `.progress` property (0–100). Pace automatically scales all sources together into a single unified progress value.
### Configuration
Set `window.paceOptions = { extraSources: [YourSourceClass], ... }`.
### Example
```javascript
function WorkerSource() {
this.progress = 0;
var self = this;
var worker = new Worker('/workers/processor.js');
worker.onmessage = function(e) {
if (e.data.type === 'progress') {
self.progress = e.data.value; // 0–100
}
if (e.data.type === 'done') {
self.progress = 100;
}
};
worker.postMessage({ cmd: 'start' });
}
window.paceOptions = {
extraSources: [WorkerSource],
// Optionally disable built-in sources
ajax: false,
document: false,
eventLag: false,
elements: false
};
```
```
--------------------------------
### Global Configuration via window.paceOptions
Source: https://context7.com/codebyzach/pace/llms.txt
Configure Pace.js behavior globally by setting the window.paceOptions object before including the pace.js script tag. This allows for customization of various tracking and timing options.
```html
```
--------------------------------
### Register custom progress sources with Pace.js
Source: https://context7.com/codebyzach/pace/llms.txt
Register custom progress sources by providing classes with a '.progress' property. Pace automatically scales all sources together into a single unified progress value. Can disable built-in sources.
```javascript
// Custom source that tracks a long-running WebWorker job
function WorkerSource() {
this.progress = 0;
var self = this;
var worker = new Worker('/workers/processor.js');
worker.onmessage = function(e) {
if (e.data.type === 'progress') {
self.progress = e.data.value; // 0–100
}
if (e.data.type === 'done') {
self.progress = 100;
}
};
worker.postMessage({ cmd: 'start' });
}
window.paceOptions = {
extraSources: [WorkerSource],
// Optionally disable built-in sources so only the worker drives progress
ajax: false,
document: false,
eventLag: false,
elements: false
};
```
--------------------------------
### Pace.restart()
Source: https://context7.com/codebyzach/pace/llms.txt
Equivalent to calling Pace.stop() then Pace.start(). It resets the progress to zero and replays the full animation. This is triggered automatically on pushState / replaceState when restartOnPushState is enabled.
```APIDOC
## Pace.restart()
Equivalent to calling `Pace.stop()` then `Pace.start()`. Resets progress to zero and replays the full animation. Triggered automatically on `pushState` / `replaceState` when `restartOnPushState` is enabled.
### Method
JavaScript
### Description
Manually triggers a restart of the progress bar, useful for SPA route changes or when handling navigation manually.
### Request Example
```javascript
// Manually trigger a restart on SPA route change
router.on('navigate', function() {
Pace.restart();
});
// Disable automatic restart and handle it manually
window.paceOptions = { restartOnPushState: false };
window.addEventListener('popstate', function() {
Pace.restart();
});
```
```
--------------------------------
### Configure Element Selectors for Progress Monitoring
Source: https://github.com/codebyzach/pace/blob/master/README.md
Specify one or more selectors in `paceOptions.elements.selectors` to monitor the presence of specific elements on the page for progress indication. Comma-separated selectors handle error states.
```javascript
paceOptions = {
elements: {
selectors: ['.timeline, .timeline-error', '.user-profile, .profile-error']
}
}
```
--------------------------------
### Manual Pace.restart() and Configuration
Source: https://context7.com/codebyzach/pace/llms.txt
Manually trigger a restart of Pace, which is equivalent to calling Pace.stop() then Pace.start(). This is useful for SPA route changes. You can also disable automatic restarts on pushState and handle them manually.
```javascript
// Manually trigger a restart — e.g., on SPA route change
router.on('navigate', function() {
Pace.restart();
});
// Disable automatic restart on pushState and handle it yourself
window.paceOptions = { restartOnPushState: false };
window.addEventListener('popstate', function() {
Pace.restart();
});
```
--------------------------------
### Configure Pace.js via Script Tag
Source: https://github.com/codebyzach/pace/blob/master/README.md
Pass Pace.js options directly within a `data-pace-options` attribute on the script tag for inline configuration.
```html
```
--------------------------------
### Pace.restart
Source: https://github.com/codebyzach/pace/blob/master/README.md
Shows the progress bar if it is hidden and resets the progress reporting from the beginning. By default, this method is automatically called whenever `pushState` or `replaceState` is invoked.
```APIDOC
## Pace.restart
### Description
Shows the progress bar if hidden and restarts progress reporting.
### Method
`Pace.restart()`
### Parameters
None
### Request Example
```javascript
Pace.restart();
```
### Response
None
```
--------------------------------
### Pace Event System
Source: https://context7.com/codebyzach/pace/llms.txt
Pace emits lifecycle events that can be subscribed to using `Pace.on`, `Pace.off`, and `Pace.once`.
```APIDOC
## Event System — `Pace.on`, `Pace.off`, `Pace.once`
Pace emits lifecycle events: `start`, `stop`, `restart`, `done`, `hide`, `progress`, and `change`. Bind handlers with `Pace.on(event, handler[, context])`, remove them with `Pace.off(event[, handler])`, and bind one-time handlers with `Pace.once`.
### Methods
- **`Pace.on(event, handler[, context])`**: Binds an event handler.
- **`Pace.off(event[, handler])`**: Removes an event handler.
- **`Pace.once(event, handler[, context])`**: Binds a one-time event handler.
### Events
- `start`: Fired when Pace begins tracking progress.
- `stop`: Fired when Pace is manually stopped.
- `restart`: Fired when Pace restarts (e.g., due to SPA navigation or a new request).
- `done`: Fired when progress reaches 100%.
- `hide`: Fired after the bar is hidden (after `ghostTime`).
- `progress`: Fired on every render tick with the current progress value.
- `change`: Fired when the progress value changes.
### Example
```javascript
// Log every lifecycle event
Pace.on('start', function() { console.log('Pace started'); });
Pace.on('done', function() { console.log('Progress reached 100%'); });
// React to progress value changes
Pace.on('progress', function(progress) {
document.title = Math.round(progress) + '% loaded';
});
// One-time handler
Pace.once('done', function() {
console.log('First load complete — removing splash screen');
});
// Remove a specific handler
function onDone() { console.log('done'); }
Pace.on('done', onDone);
Pace.off('done', onDone);
// Remove ALL handlers for an event
Pace.off('progress');
```
```
--------------------------------
### Custom Class Name (`paceOptions.className`)
Source: https://context7.com/codebyzach/pace/llms.txt
Use the `className` option to namespace Pace's progress element, allowing for multiple instances or specific styling.
```APIDOC
## Custom Class Name (`paceOptions.className`)
Use the `className` option to namespace Pace's progress element, enabling multiple Pace instances or per-page styling without conflicts.
### Configuration
Set `window.paceOptions = { className: 'your-custom-class' }`.
### Example
```javascript
window.paceOptions = {
className: 'checkout-progress'
};
```
```css
/* Target only this page's Pace bar */
.pace .pace-progress.checkout-progress {
background: linear-gradient(to right, #f7971e, #ffd200);
height: 5px;
}
```
```
--------------------------------
### Themes
Source: https://context7.com/codebyzach/pace/llms.txt
Pace includes various theme variants that can be included via CSS. Customization is possible using CSS variables or direct rule overrides.
```APIDOC
## Themes
Pace ships with theme variants. Include any theme CSS file after `pace.js`.
### Usage
Link to a theme CSS file in your HTML.
### Example
```html
```
```
--------------------------------
### Configure Pace.js Options Globally
Source: https://github.com/codebyzach/pace/blob/master/README.md
Set the global `paceOptions` object before including Pace.js to customize its behavior, such as disabling element monitoring or controlling restarts on requests.
```javascript
paceOptions = {
// Disable the 'elements' source
elements: false,
// Only show the progress on regular and ajax-y page navigation,
// not every request
restartOnRequestAfter: false
}
```
--------------------------------
### Pace.stop
Source: https://github.com/codebyzach/pace/blob/master/README.md
Hides the progress bar and ceases all progress updates.
```APIDOC
## Pace.stop
### Description
Hides the progress bar and stops updating.
### Method
`Pace.stop()`
### Parameters
None
### Request Example
```javascript
Pace.stop();
```
### Response
None
```
--------------------------------
### Pace.ignore
Source: https://github.com/codebyzach/pace/blob/master/README.md
Explicitly ignores one or more requests. Refer to the 'Tracking' section for more details.
```APIDOC
## Pace.ignore
### Description
Explicitly ignore one or more requests.
### Method
`Pace.ignore()`
### Parameters
- `requests` (Array or single request object) - The requests to ignore.
### Request Example
```javascript
Pace.ignore([
'/assets/images/logo.png',
{ url: '/api/analytics', method: 'POST' }
]);
```
### Response
None
```
--------------------------------
### Programmatic Pace.stop()
Source: https://context7.com/codebyzach/pace/llms.txt
Immediately hide the progress bar, cancel the animation loop, and reset all internal sources. This method does not fire 'done' or 'hide' events and is useful when taking manual control of Pace.
```javascript
// Stop Pace programmatically — useful when taking manual control
document.getElementById('cancel-btn').addEventListener('click', function() {
Pace.stop();
console.log(Pace.running); // false
});
```
--------------------------------
### Pace.track
Source: https://github.com/codebyzach/pace/blob/master/README.md
Explicitly tracks one or more requests. Refer to the 'Tracking' section for more details.
```APIDOC
## Pace.track
### Description
Explicitly track one or more requests.
### Method
`Pace.track()`
### Parameters
- `requests` (Array or single request object) - The requests to track.
### Request Example
```javascript
Pace.track([
'/api/data',
{ url: '/api/users', method: 'POST' }
]);
```
### Response
None
```
--------------------------------
### Manually Track AJAX Requests
Source: https://github.com/codebyzach/pace/blob/master/README.md
Use `Pace.track` to force the progress bar to be shown for specific AJAX requests.
```javascript
Pace.track(function() {
$.ajax(...)
});
```
--------------------------------
### Pace.stop()
Source: https://context7.com/codebyzach/pace/llms.txt
Immediately hides the progress bar, cancels the animation loop, and resets all internal sources. This method does not fire 'done' or 'hide' events and is useful for taking manual control.
```APIDOC
## Pace.stop()
Immediately hides the progress bar, cancels the animation loop, and resets all internal sources. Does not fire `done` or `hide` events.
### Method
JavaScript
### Description
Stops Pace programmatically, useful when taking manual control of the progress bar.
### Request Example
```javascript
document.getElementById('cancel-btn').addEventListener('click', function() {
Pace.stop();
console.log(Pace.running); // false
});
```
### Response
- **Pace.running** (boolean) - Indicates if the progress bar is currently active (will be false after calling stop).
```
--------------------------------
### Pace.track(fn)
Source: https://context7.com/codebyzach/pace/llms.txt
Forces Pace to show the progress bar for AJAX requests made within the provided callback function, overriding default tracking behavior.
```APIDOC
## `Pace.track(fn)`
Forces Pace to show the progress bar for any AJAX requests made inside the provided callback, even if they would normally be ignored.
### Parameters
- `fn` (function) - The callback function containing the AJAX requests to track.
### Example
```javascript
Pace.track(function() {
fetch('/api/submit', {
method: 'POST',
body: JSON.stringify({ name: 'Alice' }),
headers: { 'Content-Type': 'application/json' }
}).then(function(res) {
return res.json();
}).then(function(data) {
console.log('Submitted:', data);
});
});
```
```
--------------------------------
### Configure Pace.js Collectors
Source: https://github.com/codebyzach/pace/blob/master/README.md
Disable default collectors (ajax, document, eventLag) or configure the 'elements' collector with specific selectors via `paceOptions`.
```javascript
paceOptions = {
ajax: false, // disabled
document: false, // disabled
eventLag: false, // disabled
elements: {
selectors: ['.my-page']
}
};
```
--------------------------------
### Ignore URLs by Pattern
Source: https://github.com/codebyzach/pace/blob/master/README.md
Configure `ignoreURLs` in `Pace.options.ajax` to exclude specific URLs or URL patterns from tracking.
```javascript
Pace.options = {
ajax: {
ignoreURLs: ['some-substring', /some-regexp/]
}
}
```
--------------------------------
### Disable Restart on PushState
Source: https://github.com/codebyzach/pace/blob/master/README.md
Set `restartOnPushState` to `false` in `paceOptions` to prevent the progress bar from automatically restarting on pushState events, typically used for AJAX navigation.
```javascript
paceOptions = {
restartOnPushState: false
}
```
--------------------------------
### Disable AJAX Tracking Except on Navigation
Source: https://github.com/codebyzach/pace/blob/master/README.md
Set `restartOnRequestAfter` to `false` in `Pace.options` to disable AJAX tracking except for page navigation.
```javascript
Pace.options = {
restartOnRequestAfter: false
}
```
--------------------------------
### Control Restart on Long Ajax Requests
Source: https://github.com/codebyzach/pace/blob/master/README.md
Set `restartOnRequestAfter` to `false` in `paceOptions` to disable Pace from restarting on every AJAX request that lasts longer than a specified duration. This is useful for requests like precaching.
```javascript
paceOptions = {
restartOnRequestAfter: false
}
```
--------------------------------
### Disable All AJAX Tracking
Source: https://github.com/codebyzach/pace/blob/master/README.md
Set `ajax` to `false` in `Pace.options` to disable all automatic AJAX request tracking.
```javascript
Pace.options = {
ajax: false
}
```
--------------------------------
### Add Custom Class Name to Progress Bar
Source: https://github.com/codebyzach/pace/blob/master/README.md
Customize the appearance of the progress bar by adding a custom class name via the `className` option in `paceOptions`.
```javascript
paceOptions = {
className: 'my-custom-class'
}
```
--------------------------------
### Track AJAX requests with Pace.js
Source: https://context7.com/codebyzach/pace/llms.txt
Forces Pace to show the progress bar for AJAX requests made inside the callback, even if they would normally be ignored. Works with both Fetch API and XMLHttpRequest.
```javascript
// This POST would normally be ignored (only GET is tracked by default)
Pace.track(function() {
fetch('/api/submit', {
method: 'POST',
body: JSON.stringify({ name: 'Alice' }),
headers: { 'Content-Type': 'application/json' }
}).then(function(res) {
return res.json();
}).then(function(data) {
console.log('Submitted:', data);
});
});
// Works with XMLHttpRequest too
Pace.track(function() {
var xhr = new XMLHttpRequest();
xhr.open('DELETE', '/api/items/42');
xhr.send();
});
```
--------------------------------
### Manually Ignore AJAX Requests
Source: https://github.com/codebyzach/pace/blob/master/README.md
Use `Pace.ignore` to wrap AJAX calls that should not be tracked by Pace.
```javascript
Pace.ignore(function() {
$.ajax(...)
});
```
--------------------------------
### Pace.ignore(fn)
Source: https://context7.com/codebyzach/pace/llms.txt
Suppresses the progress bar for AJAX requests made within the provided callback function. Useful for background tasks that should not be visible to the user.
```APIDOC
## `Pace.ignore(fn)`
Suppresses the progress bar for any AJAX requests made inside the callback. Useful for background polling, analytics pings, or prefetch requests that should not be visible to the user.
### Parameters
- `fn` (function) - The callback function containing the AJAX requests to ignore.
### Example
```javascript
setInterval(function() {
Pace.ignore(function() {
fetch('/api/heartbeat');
});
}, 30000);
```
```
--------------------------------
### Ignore AJAX requests with Pace.js
Source: https://context7.com/codebyzach/pace/llms.txt
Suppresses the progress bar for AJAX requests made inside the callback. Useful for background polling or analytics pings that should not be visible to the user. Supports Fetch API and jQuery AJAX.
```javascript
// Heartbeat / keep-alive — should not trigger the progress bar
setInterval(function() {
Pace.ignore(function() {
fetch('/api/heartbeat');
});
}, 30000);
// jQuery AJAX inside ignore
Pace.ignore(function() {
$.ajax({ url: '/api/prefetch-data', method: 'GET' });
});
```
=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.