https://github.com/tomickigrzegorz/circular-progress-bar
⭕ A circular progress bar in svg. No dependencies. ~2KB gzip
https://github.com/tomickigrzegorz/circular-progress-bar
javascript progress-bar progress-circle svg vanilla-js
Last synced: about 1 month ago
JSON representation
⭕ A circular progress bar in svg. No dependencies. ~2KB gzip
- Host: GitHub
- URL: https://github.com/tomickigrzegorz/circular-progress-bar
- Owner: tomickigrzegorz
- License: mit
- Created: 2019-06-25T14:36:22.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2026-01-22T03:16:21.000Z (5 months ago)
- Last Synced: 2026-01-22T16:53:16.381Z (5 months ago)
- Topics: javascript, progress-bar, progress-circle, svg, vanilla-js
- Language: JavaScript
- Homepage: https://tomickigrzegorz.github.io/circular-progress-bar/
- Size: 1.1 MB
- Stars: 52
- Watchers: 1
- Forks: 15
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Circular Progress Bar
Simple circular progress bar. From now on, one call runs multiple circular-progress-bar.
## Demo
See the demo - [example](https://tomickigrzegorz.github.io/circular-progress-bar/)
## Installation
#### CDN (jsDelivr)
```html
```
#### npm
```bash
npm install @tomickigrzegorz/circular-progress-bar
# or
yarn add @tomickigrzegorz/circular-progress-bar
```
#### ESM (bundler / Vite / Webpack)
```js
import CircularProgressBar from "@tomickigrzegorz/circular-progress-bar";
```
> No CSS import needed — all styles are applied programmatically via SVG attributes.
#### ESM via CDN (no bundler)
```html
import CircularProgressBar from "https://cdn.jsdelivr.net/npm/@tomickigrzegorz/circular-progress-bar/dist/circularProgressBar.esm.min.js";
```
#### UMD (CommonJS / Node)
```js
const CircularProgressBar = require("@tomickigrzegorz/circular-progress-bar");
```
#### Local file
```html
```
## Sample configuration
1. Add a div element to the page `
`
2. Build the script or download it from the `dist` folder and add `circularProgressBar.min.js` to the page, [umd, esm, iife]
3. Call the functions `const circle = new CircularProgressBar('pie'); circle.initial();`
More extensive example:
```html
```
Arc gradient — colors follow the arc of the circle. `gradient[0]` sits at the progress start, `gradient[100%]` at the end of the visible arc, and the colors flow in the progress direction. Combines freely with `rotation`, `cut`, `inverse`, and `round`.
```html
```
Minimal configuration:
```html
```
### Function call
```javascript
// 'pie' is class name div
const circle = new CircularProgressBar("pie");
circle.initial();
```
### IntersectionObserver
Automatic animation start when the progress bar appears in the page view.
```js
window.addEventListener('DOMContentLoaded', () => {
// get all progress bar
const elements = [].slice.call(document.querySelectorAll('.pie'));
// call to function
const circle = new CircularProgressBar('pie');
// https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
// if IntersectionObserver is supported by the browser
if ('IntersectionObserver' in window) {
const config = {
root: null,
rootMargin: '0px',
threshold: 0.75,
};
const ovserver = new IntersectionObserver((entries, observer) => {
entries.map((entry) => {
if (entry.isIntersecting && entry.intersectionRatio >= 0.75) {
circle.initial(entry.target);
observer.unobserve(entry.target);
}
});
}, config);
elements.map((item) => {
ovserver.observe(item);
});
} else {
// if the browser does not support IntersectionObserver
// we run all progress bars at once
elements.map((element) => {
circle.initial(element);
});
}
});
```
### Update progress bar dynamically
Below there are properties that we can change dynamically
```js
const circle = new CircularProgressBar("pie");
circle.initial();
setTimeout(() => {
const options = {
// item number you want to update
// read data-pie-index from the element
index: 1,
// update props
percent: 30,
colorSlice: "salmon",
fontColor: "salmon",
fontSize: "1.2rem",
fontWeight: 600
};
circle.animationTo(options);
}, 3000); // after 3s update
```
Modification of these elements `fontColor`,` fontSize`, `fontWeight` is also available from the level of css. The svg text and tspan elements have unique classes on the basis of which we can modify them.
```svg
75
%
```
```css
.pie-text-1 {
fill: red;
font-size: 2rem;
/* e.t.c */
}
```
### Global configuration
```html
...
```
```js
const globalConfig = {
"strokeBottom": 5,
"colorSlice": "#EC407A",
"colorCircle": "#f1f1f1",
"round": true,
/* e.t.c */
}
const global = new CircularProgressBar('global', globalConfig);
global.initial();
```
## TypeScript
The library includes built-in TypeScript declarations — no `@types/` package needed.
```ts
import CircularProgressBar, { type CPBOptions } from "@tomickigrzegorz/circular-progress-bar";
const options: CPBOptions = {
percent: 75,
colorSlice: "#E91E63",
round: true,
};
const circle = new CircularProgressBar("pie", options);
circle.initial();
```
## Watch/Build the app
Watch the app, just call:
```bash
yarn watch
# or
npm run watch
```
Build app:
```bash
yarn build
# or
npm run build
```
## Configuration of the plugin
| props | type | default | require | description |
| -------------- | :-----------: | :---------: | :-----: | ---------------------------------------------------------------------------------------------------------- |
| percent | number | | ✔ | Represents the progress bar and animation of the animation progress expressed by a number e.g. 65% |
| index | number | `` | | Set your number `data-pie-index`, if you do not set it, it will be dynamically set depending on the order of elements |
| colorSlice | string | `'#00a1ff'` | | Progress layer color and background ["#ffff00","brown" 2](#colors-names) |
| colorCircle | string | `''` | | Bottom circle color Font ["#ffff00","brown" 2](#colors-names) |
| speed | number | `1000` | | Frame rate animation [fps]. Let's say you want the animation to be 60fps, just add the parameter speed: 60 |
| stroke | number | `10` | | Stroke width, chart thickness |
| strokeBottom | number | `10` | | If "strokBottom" is set, it is used to generate a background circle size |
| round | boolean | `false` | | Path rounding |
| inverse | boolean | `false` | | Counterclockwise animation |
| rotation | number | `-90` | | Chart rotation |
| number | boolean | `true` | | Add props number and set to false to hide the number with percent |
| animationOff | boolean | `false` | | Turn off the progress animation |
| animationSmooth| string | `''` | | Animation type setting, e.g. `500ms ease-out` - [more on transition](https://developer.mozilla.org/en-US/docs/Web/CSS/transition) |
| size | number | `200` | | Size progress bar width and height in px |
| cut | number | `0` | | Angle of the circle sector |
| unit | string | `%` | | Different unit instead of percentage (%) inside the circle 1 |
| fill | string | `none` | | Inner circle color |
| textPosition | string | `0.35em` | | The position of the SVG TEXT element vertically |
| fontSize | string | `1.6rem` | | Font size. The font can be shown in units rem, em, px ... |
| fontWeight | string | `400` | | [number, normal, bold, bolder, lighter] |
| fontColor | string | `'#000'` | | Font color ["#ffff00","brown" 2](#colors-names) |
| lineargradient | array | `` | | Array of colors "lineargradient": ["#ffff00","brown" 2](#colors-names) |
| gradient | array | `` | | Arc gradient — colors follow the arc of the circle. Array of 2–10 hex strings e.g. `["#f00","#ff0","#0f0"]` |
| gradientStops | array | `` | | Color stop positions (0–100) for `gradient`. Must match `gradient` length, otherwise equal spacing is used |
| strokeDasharray| string | `` | | It works only on the lowest circle and only on whole circles - [stroke-dasharray](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/) |
1 `unit` - you can style them. `unit` is in the tspan element of the class `pie-unit-x`. The class name is main class + `unit` + chart id. Below are the styles for our example.
```css
.pie-unit-9 {
fill: #f50057;
font-size: 1rem;
}
```
2 [See colors names](https://htmlcolorcodes.com/color-names/)
## Adding a shadow
```css
[data-pie-index='2'] {
position: relative;
border-radius: 50%;
box-shadow: inset 0 0 25px 10px rgb(162, 202, 255);
}
```
## Browser support
Supports all modern browsers (Chrome, Firefox, Safari, Edge). IE is not supported.
## License
This project is available under the [MIT](https://opensource.org/licenses/mit-license.php) license.