topbar

Tiny & beautiful site-wide progress indicator

Download .zip Download .tar.gz View on GitHub

Highlights

  • Tiny (1KB minified and gzipped), no dependency
  • Perfect for single-page/Turbolinks/pjax applications
  • Responsive

Usages

Installation

Download topbar.js or topbar.min.js and include it in the page.

<script src="path/to/topbar.js"></script>

optional: also available for Bower (bower install topbar) and Browserify (npm install topbar).

Basic

Call topbar.show() to show and topbar.hide() to hide the progress bar. Before topbar.hide() is called, the progress bar will move slower and slower but never actually reach 100%. Most of the time, these 2 methods are all you need.

Show Progress Hide Progress
$('#btnStartSimple').click(function() {
  topbar.show()
})

$('#btnStopSimple').click(function() {
  topbar.hide()
})

Delayed show

You can use topbar.show(delayMillis) to delay the progress bar. If hide() is invoked within the delay period, topbar won't show up at all. This can make the user experience feel smoother in some cases.

Show Progress Hide Progress
$('#btnStartDelayed').click(function() {
  topbar.show(500)
})

$('#btnStopDelayed').click(function() {
  topbar.hide()
})

Advanced

Use topbar.config(options) to customize topbar.

  • autoRun (default: true): if false, call topbar.progress() manually to run.
  • barThickness (default: 3): the progress bar thickness.
  • barColors: list of gradient color stops used to draw the progress bar.
  • shadowBlur (default: 10): the shadow blur.
  • shadowColor: the shadow color.
  • className: the CSS class name for the progress bar.

Note: topbar.progress() can take a number or string value. If string, you can use + or - to change the progress relatively to current position. If no argument is specified, return the current progress (0 to 1).

Show Progress Hide Progress
$('#btnStartAdvanced').click(function() {
  topbar.config({
    autoRun      : false, 
    barThickness : 5,
    barColors    : {
      '0'        : 'rgba(26,  188, 156, .7)',
      '.3'       : 'rgba(41,  128, 185, .7)',
      '1.0'      : 'rgba(231, 76,  60,  .7)'
    },
    shadowBlur   : 5,
    shadowColor  : 'rgba(0, 0, 0, .5)',
    className    : 'topbar',
  })
  topbar.show();
  (function step() {
    setTimeout(function() {  
      if (topbar.progress('+.01') < 1) step()
    }, 16)
  })()
})

$('#btnStopAdvanced').click(function() {
  topbar.hide()
})

Browsers

topbar works with any browser that supports HTML5 Canvas.