Repository files navigation

Minimalist progress bar

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

Addnprogress.js andnprogress.css to your project.

<scriptsrc='nprogress.js'></script><linkrel='stylesheet'href='nprogress.css'/>

NProgress is available viabower andnpm.

$ npm install --save nprogress

Also available viaunpkg CDN:

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

Simply callstart() anddone() to control the progress bar.

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

Ensure you're using Turbolinks 5+, and usethis: (explainedhere)

$(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 usethis: (explainedhere)

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

Try this: (explainedhere)

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

• Add progress to your Ajax calls! Bind it to the jQueryajaxStart andajaxStop events.

• Make a fancy loading bar even without Turbolinks/Pjax! Bind it to$(document).ready and$(window).load.

Percentages: To set a progress percentage, call.set(n), wheren is anumber between0..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(). Thisincrements it with a random amount. This will never get to 100%: use it forevery 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 passingtrue todone(), it will show the progress bareven if it's not being shown. (The default behavior is that.done() will notdo anything if.start() isn't called)

NProgress.done(true);

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

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

NProgress.configure({minimum:0.1});

You can change the markup usingtemplate. To keep the progressbar working, keep an element withrole='bar' in there. See thedefault templatefor reference.

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

Adjust animation settings usingeasing (a CSS easing string)andspeed (in ms). (default:ease and200)

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

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

NProgress.configure({trickle:false});

Adjust how often to trickle/increment, in ms.

NProgress.configure({trickleSpeed:200});

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

NProgress.configure({showSpinner:false});

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

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

Just editnprogress.css to your liking. Tip: you probably only want to findand replace occurrences of#29d.

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

• New UI Pattern: Website Loading Bars (usabilitypost.com)

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

Questions: ask them at StackOverflow with the tagnprogress.

Chat: join us at gitter.im.

NProgress © 2013-2017, Rico Sta. Cruz. Released under theMIT License.
Authored and maintained by Rico Sta. Cruz with help fromcontributors.

ricostacruz.com  · GitHub@rstacruz  · Twitter@rstacruz