cdowebcast / circle-progress

Responsive, accessible, animated, stylable with CSS circular progress bar available as plain (vanilla) JS and jQuery plugin.

Circle Progress

Responsive, accessible, animated, stylable with CSS circular progress bar available as plain (vanilla) JavaScript and jQuery plugin.

See examples or go to the project site

Getting Started

As plain JavaScript

Download the minified production version

In your web page:

<div class="progress"></div>

<script src="dist/circle-progress.min.js"></script>

<script>
    new CircleProgress('.progress');
</script>

As jQuery plugin

Download the minified jQuery production version

In your web page:

<div class="progress"></div>

<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="dist/jquery.circle-progress.min.js"></script>

<script>
  jQuery(function($) {
    $('.progress').circleProgress();
  });
</script>

A note about jQuery file

jQuery version of Circle Progress is built on top of plain JavaScript version. It uses jQuery Widget Factory. Two files are available: one that contains the Widget Factory code, and one that doesn't.

1. You can use the smaller jquery.circle-progress.bare.min.js, if you have already included the jQuery Widget Factory or another native jQuery widget in your page.
2. Otherwise you must use jquery.circle-progress.min.js, which includes the jQuery Widget Factory code.

Usage

Initiate Circle Progress

Plain JavaScript

const circleProgress = new CircleProgress(element, options, doc);

where

element is HTML element or selector to be converted into a progress circle (required),

options - object map of options (optional),

doc - the document we are acting upon (optional).

jQuery

$('.progress').circleProgress(options);

where options is object map of options (optional).

Options

You can customize Circle Progress with these options by either passing options object at initiation, or setting them later, e. g.:

In plain js

Set options as properties on a CircleProgress instance:

circleProgress.max = 100;
circleProgress.value = 20;

or using the chainable attr method by passing it option key and value:

circleProgress
	.attr('max', 100)
	.attr('value', 20);

or options object

circleProgress.attr({
	max: 100,
	value: 20,
});

In jQuery

$('.progress').circleProgress('value', 20);

or

$('.progress').circleProgress({
	max: 100,
	value: 20,
});

All available options

Option	Type	Default	Description
value	Number	Indeterminate	Current value
min	Number	0	Minimum value
max	Number	1	Maximum value
startAngle	Number	0	Starting angle in degrees. Angle of 0 points straight up. Direction depends on clockwise.
clockwise	Boolean	true	Whether to rotate clockwise (true) or anti-clockwise (false)
constrain	Boolean	true	Whether the value should be constrained between min and max. If true, values over max will be truncated to max and values under min will be set to min.
indeterminateText	String	'?'	Text to display as the value when it is indeterminate
textFormat	String or Function	'horizontal'	Text layout for value, min, max. You can pass either one of the possible keywords: horizontal - value/max vertical - value is shown over max percent - value% value - only value is shown valueOnCircle - the value is painted on top of the filled region on the circle none - no text is shown. Alternatively you can provide your own function, which will be called each time progress is updated with value and max as arguments and is expected to return a string to insert in the center of the progress circle
animation	String	'easeInOutCubic'	Animation easing function. One of linear, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuadr, easeOutQuadr, easeInOutQuadr or none
animationDuration	Number	600	Animation duration in milliseconds

To customize widget's appearance, you can style its underlying SVG elements with CSS. The elements are:

Class	Description
circle-progress	The svg image. You can use this selector to scale the widget. E. g.: .circle-progress {width: 200px; height: auto;}
circle-progress-circle	The entire circle (SVG circle element)
circle-progress-value	The arc representing currently filled progress (SVG path element)
circle-progress-text	Text controlled by textFormat option (SVG text element)
circle-progress-text-value	Current value text (SVG tspan element). Appears only for textFormat values of horizontal, vertical, valueOnCircle
circle-progress-text-max	Maximum value text (SVG tspan element). Appears only for textFormat values of horizontal, vertical, valueOnCircle

You can use any SVG presentation attributes on these elements. Particularly useful are: fill, stroke, stroke-width, stroke-linecap properties. (See examples)

The default options are stored in CircleProgress.defaults or jQuery.fn.circleProgress.defaults. The two are references to the same object. You can override them, so that all instances will be created with the overridden options.

Browser Support

Chrome, Firefox, Safari, Edge and IE 11 are supported.

License

© 2018 Tigran Sargsyan

Licensed under (the MIT License)