Simple slim accessible progress bars
npm install accessible-nprogressAccessible NProgress
=========
!Chrome | !Firefox | !Safari | !Opera | !Edge | !IE |
--- | --- | --- | --- | --- | --- |
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 11+ ✔ |
> Minimalist accessible progress bar (no dependencies)
Slim accessible progress bars for Ajax'y applications. Inspired by Google, YouTube, and Medium.
Originally forked from https://github.com/rstacruz/nprogress
1.0.0+ has be rewritten and only supports IE 11+ & A+ spec promises but the API is essentially the same.
For a drop in replacement of the original nprogress with accessibility fixes and older browser support then use version 0.3.0
Installation
------------
Using npm.
$ npm install --save accessible-nprogress
Using CDN:
``html`
Basic usage
-----------
Simply call start() and done() to control the progress bar.
~~~ js
NProgress.start();
NProgress.done();
~~~
~~~ js
$(document).on('turbolinks:click', function() {
NProgress.start();
});
$(document).on('turbolinks:render', function() {
NProgress.done();
NProgress.remove();
});
~~~
~~~ js
$(document).on('page:fetch', function() { NProgress.start(); });
$(document).on('page:change', function() { NProgress.done(); });
$(document).on('page:restore', function() { NProgress.remove(); });
~~~
~~~ js
$(document).on('pjax:start', function() { NProgress.start(); });
$(document).on('pjax:end', function() { NProgress.done(); });
~~~
Ideas
-----
* Add progress to your Ajax calls! Bind it to the jQuery or axios requests.
#### jQuery
~~~ js
var requests = 0;
$(document).ajaxStart(function() {
if (requests === 0) {
NProgress.start();
}
requests++;
});
$(document).ajaxStop(function() {
requests--;
if (requests === 0) {
NProgress.done();
}
});
~~~
#### Axios
~~~ js
var requests = 0;
axios.interceptors.request.use(function (config) {
if (requests === 0) {
NProgress.start();
}
requests++;
return config;
}, function (error) {
return Promise.reject(error);
});
axios.interceptors.response.use(function (response) {
requests--;
if (requests === 0) {
NProgress.done();
}
return response;
}, function (error) {
return Promise.reject(error);
});
~~~
* 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.
~~~ js
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).
~~~ js
NProgress.inc();
~~~
If you want to increment by a specific value, you can pass that as a parameter:
~~~ js
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)
~~~ js
NProgress.done(true);
~~~
__Promise:__ By passing A+ spec promises to promise(), it will automatically track progress for those promises as they complete.
~~~ js
NProgress.promise(new Promise((resolve) => setTimeout(resolve(), 1000)));
NProgress.promise(new Promise((resolve) => setTimeout(resolve(), 500)));
~~~
__Get the status value:__ To get the status value, use .status
__Get the settings value:__ To get the settings value, use .settings
Configuration
-------------
#### minimum
Changes the minimum percentage used upon starting. (default: )
~~~ js
NProgress.configure({ minimum: 0.1 });
~~~
#### template
You can change the markup using . To keep the progress bar working, keep an element with class='bar' in there. See the [default template] for reference.
~~~ js
NProgress.configure({
template: "
#### easing and speed
Adjust animation settings using easing (a CSS easing string) and speed (in ms). (default: and 200)
~~~ js
NProgress.configure({ easing: 'ease', speed: 500 });
~~~
#### trickle
Turn off the automatic incrementing behavior by setting this to . (default: true)
~~~ js
NProgress.configure({ trickle: false });
~~~
#### trickleSpeed
Adjust how often to trickle/increment, in ms.
~~~ js
NProgress.configure({ trickleSpeed: 200 });
~~~
#### showSpinner
Turn off loading spinner by setting it to false. (default: )
~~~ js
NProgress.configure({ showSpinner: false });
~~~
#### parent
specify this to change the parent container. (default: )
~~~ js
NProgress.configure({ parent: '#container' });
~~~
#### barSelector and spinnerSelector
specify this to change the selectors for the bar and spinner. (default: & div.spinner)
~~~ js
NProgress.configure({ spinnerSelector: 'div.spin' });
~~~
#### barLabel and spinnerLabel
specify this to change the aria-label for the bar and spinner. (default: )
~~~ js
NProgress.configure({ barLabel: 'fetching data' });
~~~
Customization
-------------
Just edit dist/accessible-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!
Thanks
-------
__Bugs and requests__: submit them through the project's issues tracker.
[default template]: https://github.com/nmackey/nprogress/blob/master/src/index.js#L14
[Turbolinks]: https://github.com/rails/turbolinks
[accessible-nprogress.min.js]: https://github.com/nmackey/accessible-nprogress/blob/master/dist/accessible-nprogress.min.js
[accessible-nprogress.min.css]: https://github.com/nmackey/accessible-nprogress/blob/master/dist/accessible-nprogress.min.css
Thanks
------
Acessible NProgress © 2021, Nicholas Mackey. Released under the [MIT License].
Authored and maintained by Nicholas Mackey with help from [contributors].
[MIT License]: https://mit-license.org/
[contributors]: https://github.com/nmackey/accessible-nprogress/contributors
