JavaScript Progress Bar
by Piotr Sałaciak (psalaciak 2010)
JavaScript
Usage examples1
If this code above is badly formatted, then try to use a different browser. IE or Chrome should display this code much better.
Classic usage
Progress orientation
Horizontal progress directions
Vertical progress directions
Dimensions
Rounded edges
Animated foreground
Animated progress move
Changing appearance according progress value
Custom caption
Custom caption II
Untypical usage: bar graphs
Untypical usage: equalizer
Untypical usage: poll result
Other example 1
Other example 2
Other example 3
Other example 4
Other example 5
Other example 6

Classic usage

The most common use of a progress bar is to display level of completion of some kind of process, like loading, copying or installation. It can also be used in a variety of ways, so please, check other examples.

Progress orientation

Progress bar can be horizontally or vertically oriented. Horizontal progress bar is commonly used to show loading, copying or installation process, goods ordering stage or user registration step. While vertically oriented progress bars, are mostly used to display disk usage, battery condition, fuel level or amount of some kind of energy.

Horizontal progress directions

There are two kinds of progress directions when progress bar is horizontally oriented. Progress can rise from left edge to the right edge, or which is less common, from right edge to the left edge.

Vertical progress directions

If progress bar is vertically oriented, there can be aplied two kinds of progress directions. Progress can rise from bottom edge to the top edge, or which is less common, from top edge to the bottom edge.
Loaded in 0 %

What is Your favorite cartoon character?


Features2
Supported browsers3
Supported browser logos Note that roundness and some opacity (regarding PNG alpha) is not supported by Internet Explorer and some older Opera browsers.
Documentation4

Integration

Placing ProgressBar on Your website can be made in a 3 simple steps.
1. Add JavaScript and CSS definitions.
2. Define HTML element, which You want to set as a progress bar container.
3. Add JavaScript code which will create Your progress bar.
<script type="text/javascript" src="progressbar.js"></script>
<link rel="stylesheet" type="text/css" href="progressbar.css" />

<div id="my_progress_bar"></div>

<script type="text/javascript">

	var config = {
		borderRadius: 10,
		width: 300,
		height: 20,
		imageUrl: 'images/h_fg2.png',
	};
	
	var myProgressBar = new ProgressBar("my_progress_bar", config);

</script>

Look at the configuration object property list to find out how ProgressBar can be configured. Note, that some configuration properties and also ProgressBar properties are of integer type, but instead of simple integer value an enumeration is used for a better value description.

After ProgressBar object is created, You can set it's current value by calling this method:
	myProgressBar.setValue(50);

ProgressBar Object

Properties

Name Type Default value
animationIntervalNumber (integer)100
Number of milliseconds between animation steps.
animationSmoothnessProgressBar.AnimationSmoothnessProgressBar.AnimationSmoothness.None
Indicates how progress between value A and value B is visualized. See usage example
animationSpeedNumber (float)1.0
Animation speed factor (beside animationInterval). It's value should be set between 0.1 and 3. See usage example
animationStyleProgressBar.AnimationStyleProgressBar.AnimationStyle.None
Indicates animation style that is running on a progress bar. See usage example
backgroundElementHTMLDivElementnull
HTML element that is used as a background. This property is accessible after progress bar was fully loaded (isLoaded is set to true).
backgroundUrlString(empty string)
An URL that points to a location of a progress bar background image. See usage example
borderRadiusNumber (integer)0
Determines progress bar edge rounding. See usage example
creationTypeProgressBar.CreationTypeProgressBar.CreationType.Replace
Determines how progress bar is created inside it's parent HTML element. Whether parent content is replaced with progress bar, or if progress bar is added at the end of a childNodes collection. See usage example
directionProgressBar.DirectionProgressBar.Direction.LeftToRight
Determines progress direction. It could be from left to right or from right to left for horizontal orientation. For vertical orientation it coould be from top to bottom or from bottom to top. See usage example
extraClassNameObject(see extraClassName object)
This object contains CSS class names for every HTML elements that progress bar consist of. See usage example
heightNumber (integer)20
Progress bar height (in pixels)
imageImagenull
An Image object that is used as a progress bar foreground.
imageUrlString(empty string)
An URL that points to a location of a progress bar foreground image. See usage example
isLoadedBooleanfalse
Indicates whether progress bar was fully loaded or not.
labelTextString(empty string)
Sets custom text on a progress bar. This property may contain special tags like {value} and {progress} which are replaced with appropriate values.

tag {value} - is replaced with current progress bar value,
tag {value,0} - is replaced with current progress bar value, rounded to the nearest integer,
tag {value,1} - is replaced with current progress bar value, rounded to the float number with 1 decimal digit,
tag {value,N} - is replaced with current progress bar value, rounded to the float number with N decimal digits,
tag {progress} - is replaced with percentage progress value, rounded to the nearest integer
See usage example
leftElementHTMLDivElementnull
HTML element that is used as a left part of a progress bar (or a top part in vertical orientation). This property is accessible after progress bar was fully loaded (isLoaded is set to true) and only when progress foreground image (passed during progress bar creation) width is less than whole progress bar width. Image height and progress bar height are taken in vertical orientation respectively.
markerUrlString(empty string)
An URL that points to a location of a progress bar marker image. This marker image is used with animations. It can also be set in CSS file provided with this Progress Bar solution. See usage example
maxValueNumber100
Maximal value that the progress bar can have.
middleElementHTMLDivElementnull
HTML element that is used as a middle part of a progress bar. This element is a wrapper for valueElement. This property is accessible after progress bar was fully loaded (isLoaded is set to true) and only when progress foreground image (passed during progress bar creation) width is less than whole progress bar width. Image height and progress bar height are taken in vertical orientation respectively.
minValueNumber0
Minimal value that the progress bar can have.
onAnimateFunctionnull
This function is called when progress bar is animated with interval defined in animationInterval. Note that animationStyle should be set.
onAnimationStyleChangedFunctionnull
This function is called when animationStyle property has changed.
onLoadFunctionnull
This function is called when progress bar was fully loaded.
onValueChangedFunctionnull
This function is called when progress bar value has changed.
orientationProgressBar.OrientationProgressBar.Orientation.Horizontal
Determines the progress bar orientation. It can be horizontal or vertical. See usage example
parentElementHTMLElementnull
HTML element that is used as a progress bar container.
progressNumber (float)0.0
A number between 0.0 and 1.0 that indicated the current progress.
progressPositionNumber (integer)0
Gets current progress shift in pixels, regarding progress bar width (in horizontal orientation) or height (in vertical orientation). This property could be used while extending progress bar with some extra HTML elements. See usage example
rightElementHTMLDivElementnull
HTML element that is used as a right part of a progress bar (or a bottom part in vertical orientation). This property is accessible after progress bar was fully loaded (isLoaded is set to true) and only when progress foreground image (passed during progress bar creation) width is less than whole progress bar width. Image height and progress bar height are taken in vertical orientation respectively.
showLabelBooleantrue
Determines whether label should be shown or not.
textElementHTMLDivElementnull
HTML element that is used as a progress bar label for displaying current progress.
valueNumber0
Current progress value.
valueElementHTMLDivElementnull
HTML element that is used as a progress indicator. It's contained inside middleElement. This property is accessible after progress bar was fully loaded (isLoaded is set to true) and only when progress foreground image (passed during progress bar creation) width is less than whole progress bar width. Image height and progress bar height are taken in vertical orientation respectively.
widthNumber (integer)300
Progress bar width (in pixels)
wrapperElementHTMLDivElementnull
HTML element that is used as a progress indicator. It's contained directly inside parentElement. This property is accessible after progress bar was fully loaded (isLoaded is set to true) and only when progress foreground image (passed during progress bar creation) width is greater or equal the progress bar whole width. Image height and progress bar height are taken in vertical orientation respectively.

Methods

Name Parameters Returns
setAnimationStyleProgressBar.AnimationStyle newStylevoid
Sets animation style for the ProgressBar object.

Example

myProgressBar.setAnimationStyle(ProgressBar.AnimationStyle.LeftToRight1);
setBackgroundString urlvoid
Sets new background image loaded from the given location.

Example

myProgressBar.setBackground('images/bg01.jpg');
setForegroundString urlvoid
Sets new foreground image loaded from the given location.

Example

myProgressBar.setForeground('images/pb02.jpg');
See usage example
setMarkerImageString urlvoid
Sets new marker image loaded from the given location.

Example

myProgressBar.setMarkerImage('images/marker02.jpg');
setValueNumber newValuevoid
Sets progress bar new value. If newValue is less than minValue, then minValue is used as a new value. If value is greater than maxValue, then maxValue is used as a new value.

Example

myProgressBar.setValue(67);

ProgressBar Configuration Object

Properties

Name Type Default value
animationInterval
animationSmoothness
animationSpeed
animationStyle
backgroundUrl
borderRadius
creationType
direction
extraClassName
height
imageUrl
labelText
markerUrl
maxValue
minValue
onAnimate
onAnimationStyleChanged
onLoad
onValueChanged
orientation
showLabel
width

extraClassName Object

Properties

Name Type Default value
backgroundString(empty string)
CSS class name for backgroundElement
horizontalTextString(empty string)
CSS class name for textElement when progress bar is horizontally oriented.
leftString(empty string)
CSS class name for leftElement
markerString(empty string)
CSS class name for markerElement
middleString(empty string)
CSS class name for middleElement
parentString(empty string)
CSS class name for parentElement
rightString(empty string)
CSS class name for rightElement
verticalTextString(empty string)
CSS class name for textElement when progress bar is vertically oriented.
wrapperString(empty string)
CSS class name for wrapperElement

ProgressBar Enumerations

Name Values
ProgressBar.AnimationSmoothness None : 0,
Smooth1 : 1,
Smooth2 : 2,
Smooth3 : 3,
Smooth4 : 4,
ProgressBar.AnimationStyle None : 0,
Static : 1,
StaticFull : 2,
Custom : 3,
CustomFull : 4,
Flickering1 : 10,
Flickering2 : 11,
Flickering3 : 12,
LeftToRight1 : 20,
LeftToRight2 : 21,
RightToLeft1 : 22,
RightToLeft2 : 23,
TwoWay : 24,
ProgressBar.CreationType Replace : 0,
AppendChild : 1,
ProgressBar.Direction LeftToRight : 0,
RightToLeft : 1,
TopToBottom : 0,
BottomToTop : 1,
ProgressBar.Orientation Horizontal : 0,
Vertical : 1,

HTML code for Progress Bar

Progress bar is created by adding some HTML code to element specified while calling ProgressBar constructor. If a foreground image width is smaller than progress bar width, then either for horizontal and vertical progress bar, HTML looks like that:
<div id="my_progress_bar" class="progressbar_parent">
	<div class="progressbar_background"></div>
	<div class="progressbar_left"></div>
	<div class="progressbar_middle">
		<div class=""></div>
	</div>
	<div class="progressbar_right"></div>
	<div class="progressbar_marker"></div>
	<div class="progressbar_text_horizontal">Loaded in 45 %</div>
</div>
Whereas if foreground image width is greater or equal to progress bar width, then progress bar HTML looks like that:
<div id="my_progress_bar" class="progressbar_parent">
	<div class="progressbar_background"></div>
	<div class="progressbar_wrapper"></div>
	<div class="progressbar_marker"></div>
	<div class="progressbar_text_horizontal">Loaded in 45 %</div>
</div>
Knowing this could be useful when You would like to modify progress bar appearance by CSS styles or programmatically.
JavaScript Progress Barpsalaciak 2010
If You have any question or need some help with integration, feel free to contact me. I'll do my best to assist You.
Please, take a look at my portfolio, maybe You would find something useful there. Piotr Sałaciak