Loading Bar

Flexible JavaScript 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.

<div class="ldBar"></div>

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

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

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

further tweaking is possible with following attributes:

attr namedescription
data-stroketweak stroke color or pattern
data-stroke-widthtweak stroke width
data-stroke-trailtweak trail width color
data-stroke-trail-widthtweak trail width

following examples show how to config with stroke and trail:

<div class="ldBar label-center" data-type="stroke" data-path="..." data-stroke="red" data-stroke-width="20"></div>
<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:

<div data-preset="bubble" data-pattern-size="10"></div>

Some examples of different pattern size:

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.

namedescription
data-typeset 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-dirgrowth direction of stroke type progress bar. possible value: normal / reverse
data-imgimage of fill type progress bar. could be a file name or data URI.
data-pathSVG Path command, such as M10 10L90 10. used both in stroke and fill type progress bar.
data-fillfill color, pattern or image when using a fill type progress bar with custom data-path. could be image, generated patterns or colors.
data-fill-backgroundfill color of the background shape in fill type progress bar.
data-fill-background-extrudesize of the background shape in fill type progress bar.
data-strokestroke color or pattern.
data-stroke-widthstroke width of the progress bar.
data-stroke-trailtrail color.
data-stroke-trail-widthtrail width.
data-pattern-sizespecify pattern size; e.g., 100
data-img-sizespecify image size; e.g., 200,100
data-minminimal value
data-maxmaximal value
data-precisioncontrol how values are rounded. e.g., "0.01" rounds values to second decimal place.
data-durationbar animation duration.
data-transition-inanimate 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





By continuing to browse, you agree to our use of cookies.
For more details please check our privacy policy.

loading.io loader

Loading.io is brought to you by:
PlotDB Ltd. brand logo / 見聞科技有限公司 VAT No. 52518929

Service for making ajax loaders / loading gifs / preloaders and animated icons, live background, animated text in GIF / SVG / APNG / CSS.

Customer Service: [email protected]
LOADING.IO