nprogress README

The project's README from github.com/rstacruz/nprogress. As one markdown file: README.md.

NProgress

Status npm version jsDelivr Hits

Minimalist progress bar

Slim progress bars for Ajax'y applications. Inspired by Google, YouTube, and Medium.

Installation

Add nprogress.js and nprogress.css to your project.

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

NProgress is available via bower and npm.

$ npm install --save nprogress

Also available via unpkg CDN:

Basic usage

Simply call start() and done() to control the progress bar.

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

Ensure you're using Turbolinks 5+, and use this: (explained here)

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

Ensure you're using Turbolinks 1.3.0+, and use this: (explained here)

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

Pjax

Try this: (explained here)

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

Ideas

Advanced usage

Percentages: To set a progress percentage, call .set(n), where n is a number between 0..1.

NProgress.set(0.0);     // Sorta same as .start()
NProgress.set(0.4);
NProgress.set(1.0);     // Sorta same as .done()

Incrementing: To increment the progress bar, just use .inc(). This increments it with a random amount. This will never get to 100%: use it for every image load (or similar).

NProgress.inc();

If you want to increment by a specific value, you can pass that as a parameter:

NProgress.inc(0.2);    // This will get the current status value and adds 0.2 until status is 0.994

Force-done: By passing true to done(), it will show the progress bar even if it's not being shown. (The default behavior is that .done() will not do anything if .start() isn't called)

NProgress.done(true);

Get the status value: To get the status value, use .status

Configuration

minimum

Changes the minimum percentage used upon starting. (default: 0.08)

NProgress.configure({ minimum: 0.1 });

template

You can change the markup using template. To keep the progress bar working, keep an element with role='bar' in there. See the default template for reference.

NProgress.configure({
  template: "<div class='....'>...</div>"
});

easing and speed

Adjust animation settings using easing (a CSS easing string) and speed (in ms). (default: ease and 200)

NProgress.configure({ easing: 'ease', speed: 500 });

trickle

Turn off the automatic incrementing behavior by setting this to false. (default: true)

NProgress.configure({ trickle: false });

trickleSpeed

Adjust how often to trickle/increment, in ms.

NProgress.configure({ trickleSpeed: 200 });

showSpinner

Turn off loading spinner by setting it to false. (default: true)

NProgress.configure({ showSpinner: false });

parent

specify this to change the parent container. (default: body)

NProgress.configure({ parent: '#container' });

Customization

Just edit nprogress.css to your liking. Tip: you probably only want to find and replace occurrences of #29d.

The included CSS file is pretty minimal... in fact, feel free to scrap it and make your own!

Resources

Support

Bugs and requests: submit them through the project's issues tracker.
Issues

Questions: ask them at StackOverflow with the tag nprogress.
StackOverflow

Chat: join us at gitter.im.
Chat

Thanks

NProgress © 2013-2017, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors.

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz

 

nprogress (rstacruz/nprogress)

Searching Database…

26.3K ·GitHub
Nprogress
What is this?NProgress is a minimalist JavaScript library that shows a slim progress bar at the top of the page, like the ones on YouTube or Medium, to indicate loading during Ajax requests or page transitions.
Is it a framework or just a small library?It is a tiny standalone library consisting of one JS file and one CSS file that you drop into your project, not a framework.
How do I add it to a project?Install it via npm (npm install --save nprogress) or bower, or just include nprogress.js and nprogress.css directly, or load them from the unpkg CDN.
Do I need anything else to make it work, like Turbolinks or jQuery?No, it works standalone just by calling start() and done(), but it also has built-in helpers for Turbolinks and Pjax if you use those, and you can bind it to jQuery's ajaxStart/ajaxStop events yourself.
Does the progress bar track real load percentage, or is it fake?By default it just auto-increments (trickles) toward completion rather than tracking real progress, though you can call .set(n) or .inc() manually for more precise control; trickle can be disabled.
Who would use this?Frontend developers building websites or single-page apps who want a quick visual loading indicator for page navigation or Ajax calls.
Can I customize how the bar looks?Yes, you can change the markup via the template option and restyle it by editing nprogress.css; the default color is easy to change by replacing the #29d hex code.
Can I control the animation speed and easing?Yes, the easing (CSS easing string) and speed (in ms) options control the bar's animation, defaulting to ease and 200ms.
Is the loading spinner mandatory?No, the spinner icon shown alongside the bar can be disabled with the showSpinner option, which defaults to true.
Can I get the current progress value?Yes, the current status value is exposed via the .status property.
What are similar projects?SpinKit, jquery-ui, DSH-Transparent-UI-Plugin, drawably, material-components-web, primeng, bootstrap-table, sweetalert
Which topics is it in?loading, ui-components, animation, customization, css, browser, ui, npm, frontend, library, javascript, web
Creator
rstacruz
Size
0.7 MB
Stars
26.3K
Updated
CommitApr 19Releasev0.2.0Apr 19
Age
13y
Commits · 90 Days