Jquery-circle-progress NPM

jquery-circle-progress

jQuery Plugin to draw animated circular progress bars like this:

npm.io

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: "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="{
    &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

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.

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

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