js-circle-progress
v1.0.0-beta.0
Published
Responsive, accessible, animated, stylable with CSS circular progress bar available as plain (vanilla) JS and jQuery plugin.
Downloads
6,227
Readme
Circle Progress
Lightweight (less than 4kB minified and gzipped), responsive, accessible, animated, stylable with CSS circular progress bar web component.
See examples or go to the project site
Circle Progress v1 is out! 🚀
There's been a major rewrite of Circle Progress. The new version is a web component (custom element), which can be used directly in HTML just like any native element. It can also be used programmatically in JavaScript.
The new version is not entirely backwards compatible with the old one. If you need the old version, you can still find it in the v0 branch.
This version is currently in beta. Any feedback is much appreciated.
Breaking changes since v0
New users — skip to Getting Started section below.
- Internet Explorer and Safari below version 14 are no longer supported.
- The jQuery variant of the library is no longer provided.
- The library is only shipped as an ES module.
- The
clockwise
andconstrain
properties have been revised toanticlockwise
andunconstrained
correspondingly, which have the opposite meanings and are bothfalse
by default. - Rather than using classes to style elements inside Circle Progress, such as
.circle-progress-circle
,.circle-progress-value
,.circle-progress-text
, you can now use the::part()
CSS selector, e. g.circle-progress::part(circle)
,circle-progress::part(value)
,circle-progress::part(text)
. See Styling section below or check the examples for details. - When passing a string for value, min, max or startAngle, it is now converted to number with rather than parse as float. This means you cannot pass it strings that have anything other than valid number characters. On the other hand strings which have numbers represented in any type of notation, such as scientific
1.2e7
, hexadecimal (0x1b4) or octal (0o10) are now properly converted. When making a property assignment (not attribute) you are advised to always pass numbers as numbers, not strings. - All consequent property updates are batched together and applied at once, whether set through the
attr
method or as property assignments. This means that if you set multiple properties at once, the constraints (such as keepingvalue
betweenmin
andmax
) will be applied on the new values and the component will only be updated once, which is more efficient. Once you set the properties, you can subscribe to the update if you need by awaiting thecircleProgress.updateComplete
Promise.
What hasn't changed?
- All the public properties and methods are the same (except for those mentioned above).
- The look and behavior of the component hasn't changed.
- You can still use
CircleProgress
programmatically in JavaScript in the same way as before.
Keep on reading for more details.
Getting Started
Using npm
Navigate to your project directory and install the js-circle-progress
module:
$ npm install --save js-circle-progress
Import the module anywhere in your application:
import 'js-circle-progress'
This will register the circle-progress
custom element, which you can use in your html:
<circle-progress value="50" max="100"></circle-progress>
Alternatively, you can import the module in your JavaScript and use it programmatically:
import 'js-circle-progress'
// Create an instance of CircleProgress element
const cp = document.createElement('circle-progress')
or
import CircleProgress from 'js-circle-progress'
// Create an instance of CircleProgress element
const cp = new CircleProgress()
Either way you get the same CircleProgress
element.
Manually downloading the script
Download the minified production version
Given you placed the downloaded file in the same folder as your HTML file, in your HTML:
<script src="circle-progress.min.js" type="module"></script>
<circle-progress value="50" max="100"></circle-progress>
Using a CDN
In your HTML:
<script src="https://unpkg.com/js-circle-progress/dist/circle-progress.min.js" type="module"></script>
<circle-progress value="50" max="100"></circle-progress>
Important! The script is an ES module, so you need to include it with the type="module"
attribute.
Usage
Properties
There are multiple ways to set properties on Circle Progress.
Set properties on a CircleProgress
instance:
circleProgress.max = 100;
circleProgress.value = 20;
or using the chainable attr
method by passing it property key and value:
circleProgress
.attr('max', 100)
.attr('value', 20);
or options object
circleProgress.attr({
max: 100,
value: 20,
});
When using the constructor, you can pass it options object directly at initialization:
const cp = new CircleProgress({
value: 50,
max: 100,
})
All available properties
| Option | Type | Default | Description |
| ----------------- | ------- | -------- | ----------- |
| value | Number | Indeterminate | Current value |
| min | Number | 0 | Minimum value |
| max | Number | 1 | Maximum value |
| startAngle | Number | 0 | Starting angle in degrees. Angle of 0 points straight up. Direction depends on anticlockwise
. |
| anticlockwise | Boolean | false | Whether to rotate anti-clockwise (true) or clockwise (false) |
| unconstrained | Boolean | false | Whether the value should be constrained between min
and max
. If false, values over max
will be truncated to max
and values under min
will be set to min
. |
| indeterminateText | String | '?' | Text to display as the value when it is indeterminate |
| textFormat | String or Function | 'horizontal' | Text layout for value, min, max. You can pass either one of the possible keywords: horizontal
- value/max vertical
- value is shown over max percent
- value% value
- only value is shown valueOnCircle
- the value is painted on top of the filled region on the circle none
- no text is shown. Alternatively you can provide your own function, which will be called each time progress is updated with value and max as arguments, and is expected to return a string of HTML to insert in the center of the progress circle. Attention! The string returned from your function will be inserted as HTML. Do not pass any dynamic content such as variables coming from elsewhere to avoid XSS vulnerability. |
| animation | String or Function | 'easeInOutCubic' | Animation easing function. Can be a string keyword (see the table below for available easings) or 'none'
.Alternatively, you can pass your own function with the signature function(time, startAngle, angleDiff, duration)
. The function will be called on each animation frame with the current time (milliseconds since animation start), starting angle, difference in angle (i.e. endAngle - startAngle) and animation duration as arguments, and must return the current angle. |
| animationDuration | Number | 600 | Animation duration in milliseconds |
The predefined animation easing functions:
| Easing name | Easing | | ----------- | ------ | | linear | Linear | | easeInQuad | Quadratic easing in | | easeOutQuad | Quadratic easing out | | easeInOutQuad | Quadratic easing in/out | | easeInCubic | Cubic easing in | | easeOutCubic | Cubic easing out | | easeInOutCubic | Cubic easing in/out | | easeInQuart | Quartic (power of 4) easing in | | easeOutQuart | Quartic easing out | | easeInOutQuart | Quartic easing in/out | | easeInQuint | Quintic (power of 5) easing in | | easeOutQuint | Quintic easing out | | easeInOutQuint | Quintic easing in/out | | easeInSine | Sinusoidal easing in | | easeOutSine | Sinusoidal easing out | | easeInOutSine | Sinusoidal easing in/out | | easeInExpo | Exponential easing in | | easeOutExpo | Exponential easing out | | easeInOutExpo | Exponential easing in/out | | easeInCirc | Circular easing in | | easeOutCirc | Circular easing out | | easeInOutCirc | Circular easing in/out |
Other properties and methods
updateComplete
A promise that resolves when the element has finished updating.
circleProgress.value = 50
circleProgress.max = 100
await circleProgress.updateComplete
// Do something when the update is complete
Styling
To customize widget's appearance, you can style its underlying SVG elements which are exposed as part
s with CSS.
The elements are:
| Part | Description |
| --------------------- | ----------- |
| ::part(base)
| The svg image. You can use this selector to scale the widget. E. g.: circle-progress::part(base) {width: 200px; height: auto;}
|
| ::part(circle)
| The entire circle (SVG circle element) |
| ::part(value)
| The arc representing currently filled progress (SVG path element) |
| ::part(text)
| Text controlled by textFormat
option (SVG text element) |
| ::part(text-value)
| Current value text (SVG tspan element). Appears only for textFormat values of horizontal
, vertical
, valueOnCircle
|
| ::part(text-max)
| Maximum value text (SVG tspan element). Appears only for textFormat values of horizontal
, vertical
, valueOnCircle
|
You can use any SVG presentation attributes on these elements. Particularly useful are:
fill
, stroke
, stroke-width
, stroke-linecap
properties. (See examples)
The default properties are stored in CircleProgress.defaults. You can override the values, so that all instances will be created with the overridden properties.
Usage with frameworks
Since Circle Progress is a Custom Element, which is natively supported by all modern browsers, it can freely be used with any framework, just like a standard HTML element.
Browser Support
Chrome, Firefox, Safari (starting with version 14), Edge are supported.
Contributing
If you noticed a bug or want to suggest a feature or an improvement, please do not hesitate to open an issue.
If you want to contribute code, please
- fork the repository,
- make your changes,
- run
npm run check
andnpm test
to make sure everything is ok (you can run tests in watch modenpm run test:watch
), - check the demo (index) and examples pages by running
npm start
, which will open thedocs
folder in your browser, - commit and create a pull request.
License
© 2018 Tigran Sargsyan
Licensed under (the MIT License)