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:
- Download latest GitHub release
bower install jquery-circle-progress
npm install jquery-circle-progress
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: "circleProgressEasing" } "circleProgressEasing" 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' path is required - 'jquery-circle-progress' requires it 'jquery-circle-progress': 'libs/jquery-circle-progress/dist/circle-progress' // and this one is for your convenience } }); 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
// script.js 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'); // 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.
<canvas>
Get $('.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.
CircleProgress
instance
Get 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 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 [email protected]: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
anddist/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