LoadingBar.js / Flexible JS Progress Bar Library

LoadingBar.js

LoadingBar.js is a highly flexible, open sourced progress bar library based on SVG.

Ease of Use

use it simply by adding a ldBar css class to create your own progress bar.

Rich Presets

various prebuilt styles of progress bar for you to choose, by simply adding a data-preset attribute.

data-preset="circle"

data-preset="bubble"

data-preset="line"

data-preset="fan"

Highly Configurable

You can use HTML attributes, Stylesheet or even JS API to customize it

<div class="ldBar"
  style="width:100%;height:60px",
  data-stroke="data:ldbar/res,gradient(0,1,#9df,#9fd,#df9,#fd9)",
  data-path="M10 20Q20 15 30 20Q40 25 50 20Q60 15 70 20Q80 25 90 20"
></div>

...And is Small!

plus no external dependency. just in vanilla JS.

5KB zipped

14KB unzipped

no external dependency

Installation

download loading bar JS and CSS files ( or, the zipped pack ) and include them in your HTML:

<link rel="stylesheet" type="text/css" href="loading-bar.css"/>
<script type="text/javascript" src="loading-bar.js"></script>

You can also clone the loadingBar.js Github repository and build the files by yourself.

Basic Usage

Create an element with ldBar class and set its value by data-value attribute:

<div class="ldBar" data-value="50">
</div>

By default, loadingBar.js will create a progress bar in the ldBar element for you. A corresponding ldBar JavaScript object is also created automatically and stored directly in this element, you can use the object to update bar's value with set method. Alternatively, you can use construct a new ldBar object constructor directly by passing the css selector:

<div id="myItem1"></div>
<script>
  /* construct manually */
  var bar1 = new ldBar("#myItem1");
  /* ldBar stored in the element */
  var bar2 = document.getElementById('myItem1').ldBar;
  bar1.set(60);
</script>

now you have a progress bar with default style, showing 60% as its value:

Basic Styling

Progress bars in loadingBar.js are all responsive; you can use the css width and height properties to control its size. For example, this is a huge circular progres bar with width:50% :

Additionally, stroke-type progress bars are made with path elements, so you can also control their style with common svg / css attributes:

stroke-width: 10

stroke-lincap: round

stroke: red

Elements for the base grid line and the progress bar are named with class "baseline" and "mainline" respectively. This is quite useful when you need advanced styling. Following example makes a decent circular progress bar with shadow by tickling with "mainline" and "baseline" classes:

<style type="text/css">
  .ldBar path.mainline {
    stroke-width: 10;
    stroke: #09f;
    stroke-linecap: round;
  }
  .ldBar path.baseline {
    stroke-width: 14;
    stroke: #f1f2f3;
    stroke-linecap: round;
    filter:url(#custom-shadow);
  }
</style>
<svg><defs>
<filter id="custom-shadow">
  ... (ignored)

Label Styling

In above example, we used a built-in class label-center to instruct ldBar to centralize the label:

<div
  class="ldBar label-center"
  data-value="35"
  data-preset="circle"
></div>

However, you can do your own styling by tickling the "ldBar-label" class. Label of ldBar is in fact a HTML <div> tag with "ldBar-labal" class, so you can style it with CSS like this:

<style type="text/css">
  .ldBar-label {
    color: #09f;
    font-family: 'varela round';
    font-size: 2.5em;
    font-weight: 900;
  }
  .ldBar path.mainline {
    ...
    /* styling of bar omitted */
</style>

Custom Unit

Unit in label is by default "%" and controlled by the after pseudo element, so you can change it by tweaking the after pseudo element like this:

.ldBar-label:after {
  content: "USD"; /* change from % to USD */
  font-size: 0.6em;
}

If somehow you can't use CSS to change unit, you can also specify data-unit attribute to customize unit; in this case the unit will be put in a span element inside .ldBar-label node:

<div class="ldBar label-center" data-unit="USD"
data-preset="fan" data-value="50"></div>
<style type="text/css">
  .ldBar-label span {
    font-size: 0.6em; color: #09f;
  }
</style>

Presets

Besides default progress bar, there are various presets in loadingBar for you to choose. To choose a preset, use the data-preset attribute:

<div
  data-preset="fan"
  class="ldBar label-center"
  data-value="35"
></div>

Following are the built-in presets shipped along with loadingBar.js:

line

fan

circle

bubble

rainbow

energy

stripe

text

Furthermore, you can config and customize your loading bar even if you have specified data-preset attribute. We will cover this part in the folloing section.

Advanced Styling

You can adjust the appearance of progress bar by setting HTML attribute or passing the configuration into JS constructor. But at first, we should know that there are two kinds of progress bars:

Stroke Type - Progess grows along a SVG Path.
Fill Type - Progess visualized by showing part of an image or SVG Shape.

Stroke Type Progress Bar

To use a stroke type progress bar, set data-type to "stroke" and customize your path by providing SVG Path command to the data-path attribute. Following example draws a sinle, horizontal line:

<div
  class="ldBar"
  data-type="stroke"
  data-path="M10 10L90 10">
</div>

For a more complicated example, below we draw a heart with Adobe Illustrator ( left ) and save it as SVG ( right ):

SVG Code

<svg>
<path fill="none" stroke="#ed2024" d="
M90.5,23.2c0-12.5-10.2-22.7-22.7-22.7
c-13.6,0-20.9,8.6-22.3,13.8C44.3,8.9,
35.1,0.5,23.2,0.5C10.7,0.5,0.5,10.7,
0.5,23.2c0,22.2,36.5,45.3,45,55.9
C53.5,67.3,90.5,46.3,90.5,23.2z"/>
</svg>

The Heart

we can then use the path command ( red part ) in data-path attribute of our progress bar:

HTML

<div class="ldBar label-center"
  data-type="stroke"
  data-path="M90.5,23.2c0-12.5-10
  ...( omitted )...
  46.3,90.5,23.2z"
></div>

Result

further tweaking is possible with following attributes:

attr name	description
data-stroke	tweak stroke color or pattern
data-stroke-width	tweak stroke width
data-stroke-trail	tweak trail width color
data-stroke-trail-width	tweak trail width

following examples show how to config with stroke and trail:

progress bar style

<div class="ldBar label-center"
   data-type="stroke"
   data-path="..."
   data-stroke="red"
   data-stroke-width="20"></div>

back trail style

<div class="ldBar label-center"
   data-type="stroke"
   data-path="..."
   data-stroke-trail="gray"
   data-stroke-trail-width="10"></div>

Note that alternatively you can style loading bar with CSS, as mentioned in previous section.

Fill Type Progress Bar

to use fill type progress bar, just set data-type attribute to "fill". loadingBar can fill either a path of an image, specified by data-path and data-img respectively:

<div
  data-type="fill"
  data-path="M90.5,23.2c0-12 ... 23.2z"
></div>

<div
  data-type="fill"
  data-img="kirby-dance.svg"
></div>

Image Size

LoadingBar.js use the image size to initialize the progress bar, but if you need a different size, you can use data-image-size attribute to change its size:

<div
  data-type="fill"
  data-img="myPic.gif"
  data-img-size="100,100"
></div>

Fill Direction

Direction of fill type progres bar is by default from left to right. To change this direction, use data-fill-dir:

<div data-type="fill"
  data-fill-dir="btt"
  data-img="stage.svg"
></div>

<div data-type="fill"
  data-fill-dir="ltr"
  data-img="stage.svg"
></div>

there are 4 possible values for data-fill-dir attribute:

btt - bottom to top
ttb - top to bottom
ltr - left to right
rtl - right to left

Data Range

You can use alternative data range instead of 0 ~ 100 by data-min and data-max attributes. For example, following code generates a bar that is empty with value "59" / full with value "87":

<div data-min="59"
     data-max="87">
</div>

Data Precision

LoadingBar.js rounds values by default, but you can use data-precision to control how values are rounded. To round to the fourth decimal places, use data-precision="0.0001":

<div
  data-type="fill"
  data-precision="0.0001"
></div>

Styling Background

We can also control the color and size of the base image with data-fill-background (for color) and data-fill-background-extrude (for size) attributes:

<div
  data-type="fill"
  data-fill-background="#9df"
  data-fill-dir="ltr"
  data-img="stage.svg"
></div>

<div
  data-type="fill"
  data-fill-background-extrude="5"
  data-fill-background="#9df"
  data-fill-dir="ltr"
  data-img="stage.svg"
></div>

<div
  data-type="fill"
  data-fill-background-extrude="5"
  data-fill-background="#9df"
  data-fill-dir="ltr"
  data-img="stage.svg"
></div>

Pattern Generator

To make it easier to customize your progress bar, we provide generators for generating patterns including graident, stripe and bubbles. they can be used in data-path, data-fill and data-stroke. They are designed with a data-uri favor:

'data:ldbar/res,resName(parameters...)'

currently there are 3 types of pattern available:

Gradient
Bubble
Stripe

Gradient Pattern

syntax:

data:ldbar/res,gradient(angle,duration,colors...)

example:

<div
  class="ldBar"
  data-stroke="data:ldbar/res,
  gradient(0,1,#f99,#ff9)"
></div>

Bubble

syntax:

data:ldbar/res,bubble(colorBk, colorBubble, count, duration)

example:

<div
  data-type="fill"
  data-path="M10 10L90 10L90 90L10 90Z"
  class="ldBar"
  data-fill="data:ldbar/res,
  bubble(#248,#fff,50,1)"
></div>

Stripe

syntax:

data:ldbar/res,stripe(color1, color2, duration)

example:

<div
  class="ldBar"
  data-stroke="data:ldbar/res,
  stripe(#ff9,#fc9,1)"
></div>

Custom Pattern Images

If the above generators don't fit your need, you can use your own pattern images. To use image to fill / stroke progress bar, simply put the image URL in data-fill / data-stroke attributes. For example, this progress bar is filled with a cloud animation:

 
<div
  class="ldBar"
  data-preset="bubble"
  data-pattern-size="64"
  data-fill="/cloud.svg"
  style="width:200px;height:200px"
></div>
 

While making animated patterns is not a trivial task, Loading.io provides a rich pattern library "Loading Patterns" for you to choose; here are some sample patterns from "loading patterns":

All patterns from loading.io are seamless repeatable and animatable and can still be generated in static form. Don't forget to take a look if there is anything you need.

Go to Loading Patterns

Pattern Sizing

You can specify the pattern size with data-pattern-size attribute to make pattern bigger or smaller:

Some examples of different pattern size:

pattern size = 50

pattern size = 150

pattern size = 250

JS API

You can use JavaScript to initialize a progress bar:

var bar = new ldBar( node-selector, /* Element or Selector for target element */ options /* check Reference for supported options */ );

All options are HTML attribute counterpart without data- prefix. For example, following script create a red, fan type progress bar:

<div class="myBar label-center"></div>
<script>
  var bar = new ldBar(".myBar", {
   "stroke": '#f00',
   "stroke-width": 10,
   "preset": "fan",
   "value": 65
  });
</script>

To update bar's value, simply use set method will do:

bar.set(
  50,     /* target value. */
  false   /* enable animation. default is true */
);

Reference

Here is a complete list of all configurations for loading bars.

name	description
data-type	set the progress type. can be `stroke` or `fill`.
data-fill-dir	growth direction of fill type progress bar. possible value: `ttb` / `rtl` / `ltr` / `btt`. `ttb` - top to bottom `btt` - bottom to top `ltr` - left to right `rtl` - right to left
data-stroke-dir	growth direction of stroke type progress bar. possible value: `normal` / `reverse`
data-img	image of fill type progress bar. could be a file name or data URI.
data-path	SVG Path command, such as `M10 10L90 10`. used both in stroke and fill type progress bar.
data-fill	fill color, pattern or image when using a fill type progress bar with custom data-path. could be image, generated patterns or colors.
data-fill-background	fill color of the background shape in fill type progress bar.
data-fill-background-extrude	size of the background shape in fill type progress bar.
data-stroke	stroke color or pattern.
data-stroke-width	stroke width of the progress bar.
data-stroke-trail	trail color.
data-stroke-trail-width	trail width.
data-pattern-size	specify pattern size; e.g., `100`
data-img-size	specify image size; e.g., `200,100`
data-min	minimal value
data-max	maximal value
data-precision	control how values are rounded. e.g., "0.01" rounds values to second decimal place.
data-duration	bar animation duration.
data-transition-in	animate the bar for entering transition, when value is set by data-value.

Browser Compatibility

tl;dr - Support Modern Browsers and IE >= 10

LoadingBar.js is based on several nowaday web technologies supported by modern browsers except IE.

Progress Bar Transition - based on CSS Transition and SVG filter ( IE >= 10 )
Customized Path - based on SVG ( IE >= 9 )
(Optional) Animated Patterns ( such as bubbles ) - based on SMIL ( not supported in IE / Edge )

SMIL can help keep complicated animation minimized and the patterns still look ok in IE without animation, so you can consider using them even you want to support IE >= 10. otherwise, use your own GIF for IE>=10 compatibility in animated fill patterns.

License

This project is released under MIT License; check out our Github Repo for more information.

Comments

Any questions or suggestion? Feel free to leave comment here. :)

Load Comments

Loading Bar

LoadingBar.js

Ease of Use

Rich Presets

Highly Configurable

...And is Small!

Installation

Basic Usage

Basic Styling

Label Styling

Custom Unit

Presets

Advanced Styling

Stroke Type Progress Bar

Fill Type Progress Bar

Image Size

Fill Direction

Data Range

Data Precision

Styling Background

Pattern Generator

Gradient Pattern

Bubble

Stripe

Custom Pattern Images

Pattern Sizing

JS API

Reference

Browser Compatibility

License

Comments

loading.io