rstacruz / nprogress

For slim progress bars like on YouTube, Medium, etc

NProgress

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:

• https://unpkg.com/[email protected]/nprogress.js
• https://unpkg.com/[email protected]/nprogress.css

Basic usage

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

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

Turbolinks (version 5+)

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();
});

Turbolinks (version 3 and below)

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

• Add progress to your Ajax calls! Bind it to the jQuery ajaxStart and ajaxStop 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.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

• 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.

Chat: join us at gitter.im.

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's Issues

NProgress on a custom DOM element (like div) instead of the top of the page.

This can mainly be an enhancement to have the progress bar on the desired <div> element instead of always having on the top. I was thinking something like below:

//nprogress.js
NProgress.render = function(fromStart) {
    .......
    if(Settings.target){
      $el.prependTo(Settings.target);  
    } else {
      $el.appendTo(document.body);
    }
    return $el;
  };

where target is a new setting in Settings

//Minimalist sample html
<html>
<head>
    <link href="./nprogress.css" type="text/css" rel="stylesheet"/>

    <!-- Jquery -->
    <script src="./jquery-1.9.1.min.js"></script>
    <script src="./nprogress.js"></script>
</head>
<body>
    <div>Some Content Here</div>
    <hr>

    <div id="myDiv" role='bar' style="width: 70%;">
        <table style="width: 100%">
            <tr>
                <td>
                    Something
                </td>
            </tr>
        </table>
    </div>

    <p><input type='button' id='b-1' value="Start"></input></p>
    <p><input type='button' id='b-0' value="Done"></input></p>

    <script type="text/javascript">
        NProgress.configure({
            target: '#myDiv'
        });

        $("#b-1").click(function() { NProgress.start(); });
                $("#b-0").click(function() { NProgress.done(); });
    </script>
</body>
</html>

CSS has to be modified accordingly in order to bypass the z-index

ie 7 error

SCRIPT438: Object doesn't support property or method 'querySelector'
nprogress.js, line 229 character 5

Error in animation

NProgress element is appended to a custom div in my application, rather than the body element.

NProgress CSS override:

#nprogress .bar {
  background: $nprogress-color;
  position: fixed;
  z-index: 100;
  width: 100%;
  height: 2px;
}

Provide a LESS file

What about use bootstrap variables in the file ?

Submit nprogress to npm

This is a great plugin, would love to see it on npm.

You've updated master without releasing a new tag.

Installing nprogress via bower will download the code in the 0.1.2 tag. However, that's not the latest version. You've since added support for AMD, which I would really like.

Reckon you could package that as a 0.1.3 tag?

Bug> Force ignore link like javascript:

Hi,

I have an url with href="javascript:popupModalV2('MY_URL', 'Configuration');" and the loader showed.

How can I fix this ?

Thanks

Add an `abort` command

If an enduser aborts an action it should be visually clear that the action didn't finish, e.g. by stoping the progress bar and fading it out or collapsing the bar to the left.

Can we get the percentage?

There is a '''set()''' method, so I would like to get the percentage of the progress, is there a way to make a get() function? Can I get it in current release and/or can we get it in a soon release? Or at least is it possible?

Please update bower package

eg. amd support is not in deployed package

Post to cdnjs

Would be great to have this hosted on a CDN like http://cdnjs.com/

Done should immediately clear the queue

I was trying to use this in an app where a rather large amount of images and fonts potentially get preloaded.

When they are all cached, they all complete almost simultaneously, but I get around 100 "done" events, then this causes set() to be called 100 times which queues 100 animations at a default of 500ms per animation which means you have to wait 50 seconds for the progress bar to complete even though everything is already loaded.

I thought I could quickly get around this by setting the speed to 0 before I call done(), but the speed is read out of Settings outside of the function that gets passed to queue, so it is wrapped in a closure. I ended up moving the following code inside the function:

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

But now that I think of it there will still be 100 unnecessary animations, so it probably makes more sense if done() just clears the queue before doing its thing like this:

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

  var started = NProgress.isStarted();
  var $progress = NProgress.render(!started),
  $progress.clearQueue();

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

Just something people might want to keep in mind.

Is this project still active?

@rstacruz is this still an active project? Given the amount of really good open PRs it seems it might not be...

Nprogress with Backbone

I'm trying to display nprogress when the views are being rendered using backbone. The nprogress progesses smothely, but gets stuck at the end and never stops.
How could i fix this. Below is the code snippet that im trying to do

    app.NProgress.start();

    this.collection.each( function( item ){
        this.renderPhotoSet( item );
        app.NProgress.inc();
    }, this );

    app.NProgress.done();

Insert into custom div

How does one place NProgress inside a custom div? The docs mention a template format but I'm having some trouble understanding it.

http://jsfiddle.net/frank_o/Bv2ts/

<header>
  <h1>My header</h1>
  <div role="bar">
    <!-- NProgress should go here -->
  </div>
</header>

NProgress bar does not work properly with jQuery 1.7.1

I just discovered that NProgress doesn't work on Webkit when combined with jQuery 1.7.1

The bug resides in the fact that NProgress tries to set the CSS transition and transform properties without vendor prefixes.
For example: $('.bar').css( { transition: X, transform: Y });

It seems newer versions of jQuery translate the basic property names into vendor-specific versions automatically. jQuery 1.7.1 does not do this property name interpolation and it causes the progress bar to show as 100% all the time.

The temporary workaround is to configure NProgress to positionUsing : 'margin-left'
This appears kind of jerky but it works.

The better solution is for NProgress to pass vendor-specific CSS properties using a technique like this:
http://stackoverflow.com/questions/10237731/css3-transitions-inside-jquery-css

jquery 1.7.2 issue.

Hi rstacruz, great plugin, I love it! Everything is great, except one small issue happened in jquery 1.7.2 version(not sure this also happened in 1.8+). here is the issue:

I use the inc() option, and it works in firefox, the progress bar was increase by a little, but when I view in webkit browsers, the progress bar will fast start fast to the end.

this issue was solved after i include the newest Jquery version, is it possible to fix it to the older version? Cause our website have run several years, and it's get trouble to double check all the js plugin will compatibility with the new Jquery version.

plz advise!
thx a lot!

Multitasking using jquery ajax

I am working on a application which sends multiple Jquery ajax request on the search landing page. Ajax request is send to different api's to get the search result data. Can i have one nprogress loader to all the ajax request. which closes on the all the ajax is completed

Error: useless setTimeout call (missing quotes around argument?) setTimeout(next, speed);

Helo i have this error :
on the file nprogress.js

Error: useless setTimeout call (missing quotes around argument?)
setTimeout(next, speed);
Line 87

what do u think is please ?

Documentation for "speed" is confusing

Apparently, speed should be set to the number of milliseconds. However, milliseconds is not a unit of speed, this don't make intuitive sense to me. At first, I guessed that this is the expected duration to travel between 0% to 100%, but this isn't true either.

Uncaught TypeError: undefined is not a function nprogress.js:203

Uncaught TypeError: undefined is not a function nprogress.js:203

z-index issue on progress bar fade out (with fixed-position object on the top of the page?)

I have a fixed-position box with a background colour that is fixed to the top of the page. When the progress bar fades out, for some reason it seems to quickly flash behind the top-box for a split second.

http://jsbin.com/AnIMeWu/3/

Is this an issue with the fadeout animation? Is there a way to remedy this?

Is not working with Twitter Bootstrap's NavBar component

NavBar component is overlaying/hiding the nprogress bar, It would be nice if we could show nprogress on top of NavBar, when activated. Probably via css: z-index.

Bower install failure

There were errors, here's a summary of them:
- component/jQuery component/jQuery not found

Remove jQuery dependency

What we're doing here shouldn't require a hard dependency on jQuery.

Varied trickle speed config option

Hi Rico

Thanks for the great library. I've been playing around with it a turoblinks website. One cool thing that I would like to try out is a variable or random trickle speed.

Currently when you watch the progress bar it always updates at the interval, so if the interval is one second every second the progress bar moves a varied amount which doesn't seem 100% natural. Especially for longer requests where it moves say 3-4 times.

I think it would be nice to have the option to have a varied trickle speed, so setting to to 1000ms means that a random number will be used, maybe Math.random() * Settings.trickleSpeed or Math.random() * Settings.trickleSpeed * 2

I realise you might not want to bloat up the library if it can be avoided, but it should only be 4-5 line at most and an extra config option.

Let me know what you think, if all good then i'll send you a patch with the code and documentation :)

Cheers

Indexing fail on nprogress.css style file

So, indexing fail on nprogress.css file on the line 2. I'm changed this line with this;

@before
#nprogress { pointer-events: none; }

@after
#nprogress { position:relative; pointer-events: none; z-index:99999; }

Mobile devices

Most mobile devices already do this and when both bars are going at different rates it will most likely confuse the user. Just a thought :)

Does not show if integrated with the navbar fixed of twitter bootstrap

I was trying this out with twitter bootstrap. however whenever I have a class ="navbar navbar-fixed-top" It does not show the NProgress.

Please, create missed tags for new versions

Please, create missed tags in git for new versions. Because https://rails-assets.org/ generate releases by tags.

Publish package to npm

This package isn't on the NPM registry. Please publish it to NPM so that it can be depended on using NPM.

Ditch the .spinner-icon to make it simpler.

There is no need to have a .spinner-icon inside the .spinner they could be simply merge into the .spinner and the result is exactly the same.

I could easily create a PR I'm just not sure if there is another reason to have the spinner splitted in two divs, rather than only one!

Plus if someone wants to style it differently is still possible to fit stuff inside.. I mean it's not rocket science here. but the default should be simpler..

demo site not loading

Thanks for this library. Unfortunately, it appears that your demo website is not loading: http://ricostacruz.com/nprogress

Error on file input

I get a error in the console when I have a file input in the form.

Uncaught InvalidStateError: Failed to set the 'value' property on 'HTMLInputElement': This input element accepts a filename, which may only be programmatically set to the empty string.

I posted this on the wrong github repo sorry. The progress bar works great thanks.

border-radius in the .spinner could be set to 50% instead of Npx.

So even if you're going to change the height you don't need to update the radius.

Show nprogress bar only when page is loading

Hi, i like to know how can i show nprogress bar only when page is loading
Thanks in advance.

Actual loading progression with pjax ?

I'm sorry if it has been answered elsewhere, but I only found documentation with turbolinks, but not pjax. How can I configure nprogress so it displays the "true" loading % progress of pjax requests ?

Thanks a lot !

This is my code :

$(document).pjax('a', '#pjax-container');
$(document).on('pjax:send', function() { NProgress.start(); })
$(document).on('pjax:complete', function() { NProgress.done(); })
$(document).on('pjax:timeout', function(event) { event.preventDefault(); })

From what I get it "simulates" loading, but not the actual progression. Is such a thing even possible ?

Make inc() depend on remaining space

It looks to me like this:

nprogress.js:147

amount = (1 - n) * clamp(Math.random() * n, 0.1, 0.95);

should probably be something along these lines:

amount = (1 - n) * (Math.random() * 0.1 + 0.1);

This would ensure each inc() will only increase by 10-20% of the remaining space, if I understand correctly (whereas the previous version would scale with both the remaining and elapsed space, sort of canceling itself out). This way, repeated calls to inc() will asymptotically approach the end.

Of course it could be you've thought this through and I'm just not following the logic correctly, in which case maybe a comment would make the logic clearer ;-)

White screen when progress is done

Dear friends,

when progress is done, the screen goes white in the chrome browser, i look at firefox browser and the white screen do not appear.

Sorry, but i have a sad english..

Michael.

"Uncaught Object" error in RequireJS with NProgress 1.3; 1.2 works fine

There seems to be some kind of conflict between the latest NProgress and requireJS.
After including NProgress 1.3 my initial require(..:) call creates a "Uncaught Object" error.

Have not looked into it any deeper.

Downgrading to 1.2 fixed the problem.

This cool application needs to something.

And also, this cool application needs to custom color options!.

NProgress.Queue slows progress

Wonderful progress bar. I'm integrating it into our dashboard at the moment. Our site is here see for instance this dashboard

We load about 20-30 data files in the background, sometimes. The number depends on the user navigation. I track the number of files and invoke NProgress like so:

if @req_ctr == 0
    NProgress.start()                                            # <---------------- Invoke here
    @loading true

@req_ctr += 1

---- And in Ajax callback

    @req_done += 1
    NProgress.set(@req_done / @req_ctr)                # <--------------- Invoke here
    if @req_done == @req_ctr
        @req_ctr = @req_done = 0 # All outstanding requests done.
        @loading false

-- I found that it could take seconds after all the loads were finished until the animation completed. It was because you are queuing animations, and I am putting up to 30 little animations into the queue.

My config is like this

NProgress.configure({ ease: 'ease', speed: 200 , trickle:true});

For now my solution is to limit the number of animations in the queue, but my preference is to just clear the queue and patch the correct animation every time if that is possible. Here is my current fix:

NProgress.set = function(n) {

---

$progress[0].offsetWidth; /* Repaint */

if ($progress.queue().length >= 3 && n !== 1){
    // Too many animations already in queue, don't bother.
    return;
}

I also decreased the wait between one intermediate animation and the next to avoid the last moments of the ease

  } else {
    setTimeout(next, speed * 0.9);
  }

Thanks again for the great project.

CSS

There are a few problems with the CSS stylesheet...

• w3c (prefix-less) always at the end
• The transform needs some prefixing
• -ms-animation no longer needed

See my modified version here:
http://pastebin.com/EKziUbE2

Add configuration option to disable rotating spinner

First, thank you for this project. I discovered the page:fetch and page:load events recently and was thinking about building something similar (but not nearly as unobtrusive). This project appeared at the perfect time. 😺

It seems redundant to me to have a rotating spinner and and a loading indicator bar. If the goal is to pretend to give a real progress bar, go for it. Don't mix in a indeterminate loader at the same time.

At least it should be an option. While it's easy to integrate a thin horizontal bar with basically no design changes, the rotating spinner overlays with existing navigation elements on the app I'm using it on. And it's likely to cause similar issues with other people as well.

"Uncaught TypeError" on getting body style!

Hi, there is a bug "Uncaught TypeError: Cannot read property 'style' of null " on this line ;
@216
// Sniff on document.body.style
var bodyStyle = document.body.style;

Add box-sizing to the spinner

It would be nice to have the box-sizing: border-box for the .spinner-icon (or if you agree with #25 for the .spinner) so the icon's size won't depend on the thickness of the border but only to it's dimensions.

progress visible when browser's back button used

Steps to reproduce:

1. Click any link with enabled turbolinks. Progress will appear and dissapear when page content loaded
2. Press back button in browser and you will see progress bar with spinner forever.

NProgress and jQuery Mobile

How to replace the default jQuery Mobile loader with NProgress?

http://api.jquerymobile.com/loader/

Not showing with BootStrap 2.0 even if I use z-index

The progress-bar is not showing with BootStrap 2.0 even if I use z-index to increase it.
The spinner now shows and the top is showing up but it always shows up as 100% width.

When I tried using same code on bootstrap 3.0 css, it works but when I switched to bootstrap 2.0 it sort of freezes.

I'll examine it some more and try to come up of a fix too...

Doesn't work on IE8

It doesn't work on IE8. If it's not intended, i think it's good to mention what are the supported browsers.

But let me just say: this is awesome!