jquery-circle-progress
jQuery Plugin to draw animated circular progress bars like this:
Check out more examples! Or maybe the crazy one?
Install
Make your choice:
Usage
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
<script src="jquery-circle-progress/dist/circle-progress.js"></script>
<div id="circle"></div>
<script>
$('#circle').circleProgress({
value: 0.75,
size: 80,
fill: {
gradient: ["red", "orange"]
}
});
</script>
If you use AMD or CommonJS with some JS bundler - see the UMD section below.
Options
Specify options like in 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" - { color: "#ff1e41" } - { color: 'rgba(255, 255, 255, .3)' } - { 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. Only a color fill supported by now Default: "rgba(0, 0, 0, .1)" |
animation | Animation config. See jQuery animations. You may also set it to false Default: { duration: 1200, easing: "circleProgressEase" } "circleProgressEase" is just a ease-in-out-cubic easing |
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 |
insertMode | Canvas insertion mode: append or prepend it into the parent element? Default: "prepend" |
From version 1.1.3
you can specify any config option as HTML data-
attribute.
It will work only on init, i.e. after the widget is inited you may update its properties only via .circleProgress({/*...*/})
method. data-
attributes will be ignored.
Also, object options like "fill"
or "animation"
should be valid JSON (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="{
"color": "rgba(0, 0, 0, .3)",
"image": "http://i.imgur.com/pT0i89v.png"
}"
data-reverse="true"
></div>
Events
Event | Description | Handler |
---|
circle-inited | Triggered on init or re-init. | function(event) : - event - jQuery event |
circle-animation-start | Triggered once the animation is started. | function(event) : - event - jQuery event |
circle-animation-progress | Triggered on each animation tick. | function(event, animationProgress, stepValue) : - event - jQuery event - animationProgress - from 0.0 to 1.0 - stepValue - current step value: from 0.0 to value |
circle-animation-end | Triggered once the animation is finished. | function(event) : - event - jQuery event |
Browsers support
The library uses <canvas>
which is supported by all modern browsers (including mobile browsers)
and Internet Explorer 9+ (Can I Use).
I haven't implemented any fallback / polyfill for unsupported browsers yet
(i.e. for Internet Explorer 8 and older / misc browsers).
UMD
I use UMD template for jQuery plugin which combines three things:
- works fine with browser globals
- works fine with AMD
- works fine with CommonJS
Browser globals
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
<script src="jquery-circle-progress/dist/circle-progress.js"></script>
<script>
$('#circle').circleProgress({
value: 0.75,
});
</script>
AMD
Assuming that you have jquery
, jquery-circle-progress
and requirejs
in libs/
directory:
<script src="libs/requirejs/require.js"></script>
<script>
requirejs.config({
paths: {
'jquery': 'libs/jquery/dist/jquery',
'jquery-circle-progress': 'libs/jquery-circle-progress/dist/circle-progress'
}
});
requirejs(['jquery', 'jquery-circle-progress'], function($) {
$('#circle').circleProgress({
value: 0.75
});
});
</script>
You can configure RequireJS as you wish, just make 'jquery'
dependency reachable.
CommonJS
require('jquery-circle-progress');
var $ = require('jquery');
$('#circle').circleProgress({
value: 0.75
});
some-js-bundler < script.js > script.bundle.js
<script src="script.bundle.js"></script>
You can use any JS bundler (Webpack, Browserify, etc) - no specific configuration required.
API
Get/set value
Get it:
$('.circle').circleProgress({ value: 0.5 });
var value = $('.circle').circleProgress('value');
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);
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');
$('#circle').circleProgress();
$('#circle').circleProgress({ size: 150 });
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 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 imlpement 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.
Development
Install
git clone git@github.com:kottenator/jquery-circle-progress.git
npm install
Modify
You need to update dist/circle-progress.min.js
after any change to dist/circle-progress.js
:
npm run build-min
If you're using one of JetBrains IDEs - you can configure a File Watcher.
It's also possible to use some CLI tool like Watchman.
Test
npm test
SauceLabs:
export SAUCE_USERNAME=...
export SAUCE_ACCESS_KEY=...
export BUILD_NUMBER=...
npm test -- karma-saucelabs.conf.js
Build docs
The API docs are not complete yet but you can build them:
npm run build-docs
They will be generated in docs/api/
.
Release new version
-
finalize the code
-
update the version in package.json
, bower.json
and dist/circle-progress.js
docstring
-
update min dist: npm run build-min
-
update docs/index.html
- link to the latest dist version (which doesn't exist yet)
-
push the changes to master
branch
-
release on Bower: just create a Git tag (e.g.): git tag v1.2.3 && git push --tags
-
release on GitHub - add release notes to the Git tag
-
release on NPM: npm publish
, but be aware:
Once a package is published with a given name and version, that specific name and version combination can never be used again - NPM docs