api documentation for nprogress (v0.2.0)

Simple slim progress bars

module nprogress
1. function nprogress.configure (options)
2. function nprogress.done (force)
3. function nprogress.getPositioningCSS ()
4. function nprogress.inc (amount)
5. function nprogress.isRendered ()
6. function nprogress.isStarted ()
7. function nprogress.promise ($promise)
8. function nprogress.remove ()
9. function nprogress.render (fromStart)
10. function nprogress.set (n)
11. function nprogress.start ()
12. function nprogress.trickle ()
13. object nprogress.settings
14. object nprogress.status
15. string nprogress.version

module nprogress

function nprogress.configure (options)

description and source-code

configure = function (options) {
  var key, value;
  for (key in options) {
    value = options[key];
    if (value !== undefined && options.hasOwnProperty(key)) Settings[key] = value;
  }

  return this;
}

example usage

...
Configuration
-------------

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

~~~ js
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.
...

function nprogress.done (force)

description and source-code

done = function (force) {
  if (!force && !NProgress.status) return this;

  return NProgress.inc(0.3 + 0.5 * Math.random()).set(1);
}

example usage

...
Basic usage
-----------

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

~~~ js
NProgress.start();
NProgress.done();
~~~

Using [Turbolinks] or similar? Ensure you're using Turbolinks 1.3.0+, and use
this: (explained
    [here](https://github.com/rstacruz/nprogress/issues/8#issuecomment-23010560))

~~~ js
...

function nprogress.getPositioningCSS ()

description and source-code

getPositioningCSS = function () {
  // Sniff on document.body.style
  var bodyStyle = document.body.style;

  // Sniff prefixes
  var vendorPrefix = ('WebkitTransform' in bodyStyle) ? 'Webkit' :
                     ('MozTransform' in bodyStyle) ? 'Moz' :
                     ('msTransform' in bodyStyle) ? 'ms' :
                     ('OTransform' in bodyStyle) ? 'O' : '';

  if (vendorPrefix + 'Perspective' in bodyStyle) {
    // Modern browsers with 3D support, e.g. Webkit, IE10
    return 'translate3d';
  } else if (vendorPrefix + 'Transform' in bodyStyle) {
    // Browsers without 3D support, e.g. IE9
    return 'translate';
  } else {
    // Browsers without translate() support, e.g. IE7-8
    return 'margin';
  }
}

example usage

...
  speed    = Settings.speed,
  ease     = Settings.easing;

    progress.offsetWidth; /* Repaint */

    queue(function(next) {
// Set positionUsing if it hasn't already been set
if (Settings.positionUsing === '') Settings.positionUsing = NProgress.getPositioningCSS
();

// Add transition
css(bar, barPositionCSS(n, speed, ease));

if (n === 1) {
  // Fade out
  css(progress, {
...

function nprogress.inc (amount)

description and source-code

inc = function (amount) {
  var n = NProgress.status;

  if (!n) {
    return NProgress.start();
  } else {
    if (typeof amount !== 'number') {
      amount = (1 - n) * clamp(Math.random() * n, 0.1, 0.95);
    }

    n = clamp(n + amount, 0, 0.994);
    return NProgress.set(n);
  }
}

example usage

...

~~~ 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();
~~~
...

function nprogress.isRendered ()

description and source-code

isRendered = function () {
  return !!document.getElementById('nprogress');
}

example usage

...

  /**
   * (Internal) renders the progress bar markup based on the `template`
   * setting.
   */

  NProgress.render = function(fromStart) {
if (NProgress.isRendered()) return document.getElementById('nprogress');

addClass(document.documentElement, 'nprogress-busy');

var progress = document.createElement('div');
progress.id = 'nprogress';
progress.innerHTML = Settings.template;
...

function nprogress.isStarted ()

description and source-code

isStarted = function () {
  return typeof NProgress.status === 'number';
}

example usage

...
   * Sets the progress bar status, where `n` is a number from `0.0` to `1.0`.
   *
   *     NProgress.set(0.4);
   *     NProgress.set(1.0);
   */

  NProgress.set = function(n) {
var started = NProgress.isStarted();

n = clamp(n, Settings.minimum, 1);
NProgress.status = (n === 1 ? null : n);

var progress = NProgress.render(!started),
    bar      = progress.querySelector(Settings.barSelector),
    speed    = Settings.speed,
...

function nprogress.promise ($promise)

description and source-code

promise = function ($promise) {
  if (!$promise || $promise.state() === "resolved") {
    return this;
  }

  if (current === 0) {
    NProgress.start();
  }

  initial++;
  current++;

  $promise.always(function() {
    current--;
    if (current === 0) {
        initial = 0;
        NProgress.done();
    } else {
        NProgress.set((initial - current) / initial);
    }
  });

  return this;
}

example usage
```
n/a
```

function nprogress.remove ()

description and source-code

remove = function () {
  removeClass(document.documentElement, 'nprogress-busy');
  removeClass(document.querySelector(Settings.parent), 'nprogress-custom-parent');
  var progress = document.getElementById('nprogress');
  progress && removeElement(progress);
}

example usage

...
Using [Turbolinks] or similar? Ensure you're using Turbolinks 1.3.0+, and use
this: (explained
   [here](https://github.com/rstacruz/nprogress/issues/8#issuecomment-23010560))

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

Ideas
-----

* Add progress to your Ajax calls! Bind it to the jQuery `ajaxStart` and
`ajaxStop` events.
...

function nprogress.render (fromStart)

description and source-code

render = function (fromStart) {
  if (NProgress.isRendered()) return document.getElementById('nprogress');

  addClass(document.documentElement, 'nprogress-busy');

  var progress = document.createElement('div');
  progress.id = 'nprogress';
  progress.innerHTML = Settings.template;

  var bar      = progress.querySelector(Settings.barSelector),
      perc     = fromStart ? '-100' : toBarPerc(NProgress.status || 0),
      parent   = document.querySelector(Settings.parent),
      spinner;

  css(bar, {
    transition: 'all 0 linear',
    transform: 'translate3d(' + perc + '%,0,0)'
  });

  if (!Settings.showSpinner) {
    spinner = progress.querySelector(Settings.spinnerSelector);
    spinner && removeElement(spinner);
  }

  if (parent != document.body) {
    addClass(parent, 'nprogress-custom-parent');
  }

  parent.appendChild(progress);
  return progress;
}

example usage

...

  NProgress.set = function(n) {
var started = NProgress.isStarted();

n = clamp(n, Settings.minimum, 1);
NProgress.status = (n === 1 ? null : n);

var progress = NProgress.render(!started),
    bar      = progress.querySelector(Settings.barSelector),
    speed    = Settings.speed,
    ease     = Settings.easing;

progress.offsetWidth; /* Repaint */

queue(function(next) {
...

function nprogress.set (n)

description and source-code

set = function (n) {
  var started = NProgress.isStarted();

  n = clamp(n, Settings.minimum, 1);
  NProgress.status = (n === 1 ? null : n);

  var progress = NProgress.render(!started),
      bar      = progress.querySelector(Settings.barSelector),
      speed    = Settings.speed,
      ease     = Settings.easing;

  progress.offsetWidth; /* Repaint */

  queue(function(next) {
    // Set positionUsing if it hasn't already been set
    if (Settings.positionUsing === '') Settings.positionUsing = NProgress.getPositioningCSS();

    // Add transition
    css(bar, barPositionCSS(n, speed, ease));

    if (n === 1) {
      // Fade out
      css(progress, {
        transition: 'none',
        opacity: 1
      });
      progress.offsetWidth; /* Repaint */

      setTimeout(function() {
        css(progress, {
          transition: 'all ' + speed + 'ms linear',
          opacity: 0
        });
        setTimeout(function() {
          NProgress.remove();
          next();
        }, speed);
      }, speed);
    } else {
      setTimeout(next, speed);
    }
  });

  return this;
}

example usage

...

 * 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()
~~~
...

function nprogress.start ()

description and source-code

start = function () {
  if (!NProgress.status) NProgress.set(0);

  var work = function() {
    setTimeout(function() {
      if (!NProgress.status) return;
      NProgress.trickle();
      work();
    }, Settings.trickleSpeed);
  };

  if (Settings.trickle) work();

  return this;
}

example usage

...

Basic usage
-----------

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

~~~ js
NProgress.start();
NProgress.done();
~~~

Using [Turbolinks] or similar? Ensure you're using Turbolinks 1.3.0+, and use
this: (explained
[here](https://github.com/rstacruz/nprogress/issues/8#issuecomment-23010560))
...

function nprogress.trickle ()

description and source-code

trickle = function () {
  return NProgress.inc(Math.random() * Settings.trickleRate);
}

example usage

...
   */
  NProgress.start = function() {
if (!NProgress.status) NProgress.set(0);

var work = function() {
  setTimeout(function() {
    if (!NProgress.status) return;
    NProgress.trickle();
    work();
  }, Settings.trickleSpeed);
};

if (Settings.trickle) work();

return this;
...

[ this document was created with utility2 ]

api documentation for nprogress (v0.2.0)

Simple slim progress bars

table of contents