jQuery Circular Progress Plugin - improved

Monday 17th of August 2015

Just because I've not written enough jQuery plugins lately (hmmm), here's another one. It's based on a plugin that I wrote a few years ago but never properly finished or made public. Here it is - the much improved, no images involved, circular progress indicator.

(if you didn't see it animate, reload the page)

Getting started

To initialise the plugin, first include jQuery, the plugin and the plugin's stylesheet.

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script src="circularprogress.jquery.min.js"></script>
<link rel="stylesheet" type="text/css" href="circularprogress.css"/>

Add some markup:

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

Then call the plugin.

<script>
$(document).ready(function(){$('.example1').circles({targetPos: 200});
});
</script>

It works in all modern browsers (that I've tested) and even IE9. Unfortunately because it relies on CSS3 rounded corners and rotations, it won't work in IE8 or below.

That should be all you need to get started, but you'll likely want to do more with it. Full details are on my github but there's a few more examples below.

Scale

The plugin defaults to using a 360 degree scale for progress but this can be changed to any number below that using the 'scale' option. Here are two likely use case examples.

100%

$('.example2').circles({scale: 100,targetPos:75,showProgress:1
});

Step 1 of 5

$('.example3').circles({scale: 5,targetPos:3,showProgress:1
});

Putting stuff inside the circle

Include an inner

$('.example4').circles({targetPos:260,includeInner: 1
});

Inner with text

$('.example5').circles({targetPos:260,innerHTML: 'some text'
});

Inner with current progress

$('.example6').circles({targetPos:260,showProgress: 1
});

If a circle outline shaped progress bar is required instead of the default filled circle, simply add the option 'includeInner'. If some arbitrary text should go inside the circle, add the option 'innerHTML' with the text required. The plugin doesn't include any specific styling for text within the circle (that I leave to you, the example uses some sneaky break tags). If the position of the progress indicator should be displayed (and dynamically updated as the position changes) use the option 'showProgress'.

Note that using either the 'innerHTML' or 'showProgress' options removes the need to explicitly set the 'includeInner' option. 'includeInner' is only needed if a blank inner is required.

The plugin will also accept two options that set text to appear immediately before and after the displayed progress:

$('.example7').circles({scale:5,targetPos:3,showProgress: 1,progPreText:'Step ',progPostText:' of 5'
});

Speed and step

By default the plugin animates smoothly at a reasonable speed. It is however possible to adjust these options to produce a stepped animation effect, as shown.

$('.example8').circles({scale:5,targetPos:4,showProgress: 1,progPreText:'Step ',progPostText:' of 5',speed:600,rotateBy: 360 / 5
});

Callback and public method

To further improve the usefulness of the plugin, there's also a public method to change position and an optional callback that fires when the progress has finished moving.

Moving...

$('.example9').circles({scale:5,targetPos:3,showProgress: 1,progPreText:'Step ',progPostText:' of 5',onFinishMoving:function(pos){$('#output').html('Stopped at ' + pos);}
});$('#test1').click(function(e){e.preventDefault();var test1 = $('.example9').data('circles');test1.moveProgress($('#test1num').val());
});

Further notes

I've kept the styling fairly simple to allow for freedom to change the appearance, rather than complicate things unnecessarily. The LESS is included in the repo, it should hopefully make sense to anyone who knows what they're doing.

There's also at least one more option that I've not provided an example for, details are in the repo.

The original plugin did essentially the same as this one, only it wasn't quite as good. It also included the option to output the progress as a horizontal or vertical bar. When I started writing the new version I decided not to include this functionality, partly because there are loads of plugins that do that already and partly because it seemed to detract from the point. If you really want a plugin that does both, let me know and I'll consider adding it back in.

Related