circle-progress

Animated circular progress bars like this:

Formerly known as jquery-circle-progress, now it doesn't depend on jQuery. But if you do want jQuery - jquery-circle-progress still exists as jQuery adapter for this library.

Check out more examples! Or maybe the crazy one? TODO

Install

Download latest GitHub release or bower install circle-progress.

Usage

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

<div id="circle"></div>

<script>
    new CircleProgress({
        el: document.getElementById("circle"),
        value: 0.75,
        size: 80,
        fill: {
            gradient: ["red", "orange"]
        }
    });
</script>

Options

You should specify options like in usage example above.

| Option | Description | | ---- | ---- | ---- | | value | This is the only required option. It should be from 0.0 to 1.0.
Default: 0 | | size | Size of the circle / canvas in pixels.
Default: 100 | | startAngle | Initial angle (for 0 value).
Default: -Math.PI | | reverse | Reverse animation and arc draw
Default: false | | thickness | Width of the arc. By default it's automatically calculated as 1/14 of size but you may set your own number.
Default: "auto" | | lineCap | Arc line cap: "butt", "round" or "square" - read more.
Default: "butt" | fill | The arc fill config. You may specify next:
- "#ff1e41" (CSS color spec)
- { color: "#ff1e41" } (same as above)
- { gradient: ["red", "green", "blue"] }
- { gradient: [["red", .2], ["green", .3], ["blue", .8]] }
- { gradient: [ ... ], gradientAngle: Math.PI / 4 }
- { gradient: [ ... ], gradientDirection: [x0, y0, x1, y1] }
- { image: "http://i.imgur.com/pT0i89v.png" }
- { image: imageInstance }
- { color: "lime", image: "http://i.imgur.com/pT0i89v.png" }
Default: { gradient: ["#3aeabb", "#fdd250"] } | | emptyFill | Color of the "empty" arc. The same fill options as above.
Default: "rgba(0, 0, 0, .1)" | | animation | Animation config TODO.
You may also set it to false.
Default: ... | | animationStartValue | Default animation starts at 0.0 and ends at specified value. Let's call this direct animation. If you want to make reversed animation then you should set animationStartValue to 1.0. Also you may specify any other value from 0.0 to 1.0.
Default: 0.0

You can specify any config option as HTML data- attribute.

It will work only on init, i.e. after the widget is initiated you can modify the instance properties but changing data- attributes will give no effect.

Also, complex options like "fill" should be in valid JSON format (and don't forget about HTML escaping):

<div
    class="circle"
    data-value="0.9"
    data-size="60"
    data-thickness="20"
    data-animation-start-value="1.0"
    data-fill="{
        &quot;color&quot;: &quot;rgba(0, 0, 0, .3)&quot;,
        &quot;image&quot;: &quot;http://i.imgur.com/pT0i89v.png&quot;
    }"
    data-reverse="true"
></div>

Events

When animation is enabled, there are 3 events available:

Event	Handler
circle-animation-start	function(event): - event - event object (TODO)
circle-animation-progress	function(event, animationProgress, stepValue): - event - event object (TODO) - animationProgress - from 0.0 to 1.0 - stepValue - current step value: from 0.0 to value
circle-animation-end	function(event): - event - event object (TODO)

Browsers support

It uses <canvas> which is supported by all modern browsers (including mobile browsers) and Internet Explorer 9+ (Can I Use).

I have not implemented any fallback / polyfill for unsupported browsers yet (i.e. for Internet Explorer 8 and older / misc browsers).

---

Further documentation is not processed yet! TODO

API

Get/set value

Get it:

$('.circle').circleProgress({ value: 0.5 });
var value = $('.circle').circleProgress('value'); // 0.5

It will return the first item's value (by first I mean when $('.circle').length >= 1). It works only if the widget is already inited. Raises an error otherwise.

Set it:

$('.circle').circleProgress('value', 0.75); // set value to 0.75 & animate the change 

It will update all selected items value and animate the change. It doesn't redraw the widget - it updates the value & animates the changes. For example, it may be an AJAX loading indicator, which shows the loading progress.

Get <canvas>

$('.circle').circleProgress({ value: 0.5 });
var canvas = $('.circle').circleProgress('widget');

It will return the first item's <canvas> (by first I mean when $('.circle').length >= 1). It works only if the widget is already inited. Raises an error otherwise.

Get CircleProgress instance

var instance = $('#circle').data('circle-progress');

Redraw existing circle

$('#circle').circleProgress({ value: 0.5, fill: { color: 'orange' }});
$('#circle').circleProgress('redraw'); // use current configuration and redraw
$('#circle').circleProgress(); // alias for 'redraw'
$('#circle').circleProgress({ size: 150 }); // set new size and redraw

It works only if the widget is already inited. Raises an error otherwise.

Change default options

$.circleProgress.defaults.size = 50;

FAQ

How to start the animation only when the circle appears in browser's view (on scrolling)?

Here is my proposed solution.

How to make the size flexible?

E.g. for Retina support or for responsive design, you can do it in the following way.

What if I need it to run in IE8?

There is no full-feature support for IE8 (actually, I didn't implement IE8 support at all). But you may follow my recommendations.

How to stop the animation?

Here is what you can do.

Can I handle "click" event?

It's not in the "core" but you can use my example of mouse/touch events handling.

May I customize the shape somehow?

It's a bit "tricky" but possible. Here is my little collection.