NProgress

You can install NProgress using npm or include the assets directly via CDN.

Using npm:

$ npm install --save nprogress

Using CDN (unpkg):

• JS: https://unpkg.com/nprogress@0.2.0/nprogress.js
• CSS: https://unpkg.com/nprogress@0.2.0/nprogress.css

Manual Setup: Ensure both nprogress.js and nprogress.css are added to your project and linked in your HTML.

<script src='nprogress.js'></script>
<link rel='stylesheet' href='nprogress.css'/>

Use NProgress.configure() to customize the behavior and appearance of the progress bar.

Available configuration keys:

• minimum: Minimum percentage upon starting (default: 0.08).
• template: Custom HTML markup. Must include an element with role='bar'.
• easing: CSS easing string (default: 'ease').
• speed: Animation speed in ms (default: 200).
• trickle: Boolean to enable/disable automatic incrementing (default: true).
• trickleSpeed: Interval for trickle/increment in ms (default: 200).
• showSpinner: Boolean to show/hide the loading spinner (default: true).
• parent: The container element (default: body).

NProgress.configure({
  minimum: 0.1,
  easing: 'ease',
  speed: 500,
  trickle: false,
  showSpinner: false,
  parent: '#container'
});

For Turbolinks 1.3.0+, use these event listeners:

$(document).on('page:fetch',   function() { NProgress.start(); });
$(document).on('page:change',  function() { NProgress.done(); });
$(document).on('page:restore', function() { NProgress.remove(); });

For Turbolinks 5+, use the following event listeners to trigger the progress bar during page transitions:

$(document).on('turbolinks:click', function() {
  NProgress.start();
});
$(document).on('turbolinks:render', function() {
  NProgress.done();
  NProgress.remove();
});

For Pjax, bind the progress bar to the following events:

$(document).on('pjax:start', function() { NProgress.start(); });
$(document).on('pjax:end',   function() { NProgress.done();  });

NProgress provides fine-grained control over the progress state:

• Set specific percentage: Use .set(n) where n is a number between 0..1.
• Increment progress: Use .inc() to increment by a random amount (useful for image loads). Use .inc(n) to increment by a specific value (e.g., 0.2). Note that incrementing will never reach 100%.
• Force completion: Call .done(true) to show the progress bar even if .start() was never called.
• Get current status: Access the current progress value via the .status property.

NProgress.set(0.4);     // Set to 40%
NProgress.inc(0.2);     // Increment by 0.2
NProgress.done(true);   // Force completion
console.log(NProgress.status); // Get current status

Control the progress bar manually by calling start() to begin the progress animation and done() to complete it.

NProgress.start();
NProgress.done();

If you are using jQuery, NProgress.promise($promise) allows you to track the progress of one or more jQuery promises.

When you pass a promise to this method, NProgress starts the bar. As each promise resolves, the progress bar increments. Once all supplied promises have resolved, NProgress.done() is called automatically.

Note: This method requires the presence of jQuery and expects the promise to have a .state() method and an .always() method.

// Example with a single jQuery promise
const myPromise = $.ajax('/api/data');
NProgress.promise(myPromise);

// Example with multiple promises
const p1 = $.ajax('/api/1');
const p2 = $.ajax('/api/2');
NProgress.promise(p1);
NProgress.promise(p2);

You can query the current state of NProgress using these methods:

• NProgress.isStarted(): Returns true if the progress bar is currently active (i.e., NProgress.status is a number).
• NProgress.isRendered(): Returns true if the progress bar element is currently present in the DOM.
• NProgress.status: A property that holds the current progress value (a number from 0.0 to 1.0). It is null when the bar is not active.