NProgress
Slim progress bars for Ajax'y applications. Inspired by Google, YouTube, and Medium.
Installation
Add nprogress.js and nprogress.css to your project.
NProgress is available via bower and npm and spm.
$ bower install --save nprogress
$ npm install --save nprogress
Basic usage
Simply call start()
and done()
to control the progress bar.
NProgressstart;NProgress;
Using Turbolinks or similar? Ensure you're using Turbolinks 1.3.0+, and use this: (explained here)
;;;
Ideas
-
Add progress to your Ajax calls! Bind it to the jQuery
ajaxStart
andajaxStop
events. -
Make a fancy loading bar even without Turbolinks/Pjax! Bind it to
$(document).ready
and$(window).load
.
Advanced usage
Percentages: To set a progress percentage, call .set(n)
, where n is a
number between 0..1
.
NProgress; // Sorta same as .start()NProgress;NProgress; // 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;
If you want to increment by a specific value, you can pass that as a parameter:
NProgress; // 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;
Get the status value: To get the status value, use .status
Configuration
minimum
Changes the minimum percentage used upon starting. (default: 0.08
)
NProgress;
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;
easing
and speed
Adjust animation settings using easing (a CSS easing string)
and speed (in ms). (default: ease
and 200
)
NProgress;
trickle
Turn off the automatic incrementing behavior by setting this to false
. (default: true
)
NProgress;
trickleRate
and trickleSpeed
You can adjust the trickleRate (how much to increase per trickle) and trickleSpeed (how often to trickle, in ms).
NProgress;
showSpinner
Turn off loading spinner by setting it to false. (default: true
)
NProgress;
parent
specify this to change the parent container. (default: body
)
NProgress;
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
- New UI Pattern: Website Loading Bars (usabilitypost.com)
Support
Bugs and requests: submit them through the project's issues tracker.
Questions: ask them at StackOverflow with the tag nprogress.
Thanks
NProgress © 2013-2014, 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