vue-ellipse-progress
Advanced tools
A Vue.js component to create beautiful animated circle progress bars
A dependency-free simple, flexible and smooth Vue.js plugin to create beautiful circle progress bars, implemented with SVG. Start creating circles in three steps:
// install
npm i vue-ellipse-progress@next
// initialize
import veProgress from "vue-ellipse-progress";
createApp(App).use(veProgress);
// use
<ve-progress :progress="50"/>
ā Take a look at some interesting examples on the Demo page ā
Use your package manager or CDN to install and initialize the component.
Installation via npm:
npm i vue-ellipse-progress@next
After the installation you have the choice to initialize the component as a plugin or to import it directly.
Import and initialize the component in your main.js. After initialization, the component is available as <ve-progress/>.
You can also define a custom name:
import { createApp } from "vue";
import veProgress from "vue-ellipse-progress";
createApp(App).use(veProgress);
// createApp(App).use(veProgress, "vep"); define custom name
You also have the option to import the component directly:
import { VeProgress } from "vue-ellipse-progress";
To use the component without a build tool you can customize and get the veprogress.umd.min.js file from JSDelivr.
Just add the following line to your HTML and initialize the component as plugin:
<script src="https://cdn.jsdelivr.net/npm/vue-ellipse-progress/dist/veprogress.umd.min.js"></script>
...
createApp(App).use(veprogress);
After you have initialized the component, you are ready to create your circles:
<ve-progress
:progress="progress"
:data="circles"
:angle="-90"
color="blue"
:color-fill="colorFillGradient"
empty-color="#8ec5fc"
:empty-color-fill="emptyColorFillGradient"
:size="300"
:thickness="10"
empty-thickness="10%"
line-mode="in 10"
line-position="out 10"
empty-line-position="in"
:hide-legend="false"
:legend="180"
:legend-formatter="({currentValue}) => new Intl.NumberFormat('de-DE').format(currentValue)"
legend-class="legend-custom-style"
dash="60 0.9"
animation="reverse 700 400"
:noData="false"
:loading="false"
:loader="{ color: 'green' }"
font-color="white"
:half="false"
:gap="10"
dot="10 blue"
reverse
font-size="5rem">
<span slot="legend">/200</span>
<p slot="legend-caption">GOOD JOB</p>
</ve-progress>
The progress is the only required property, and you are ready to go with just following line:
<ve-progress :progress="progress"/>
Also make sure to check slot options
| Prop | Type | Values | Default |
|---|---|---|---|
progress | Number | [-100, 100] | |
size | Number | >=0 | 200 |
line | String | "round | square | butt" | "round" |
thickness | Number | String | >=0 as Number or percent value as String | "5%" |
lineMode | String | "center | out | out-over | in | in-over | top | bottom [offset]" | "center" |
linePosition | String | "center | out | in [offset]" | "center" |
emptyLinePosition | String | "center | out | in [offset]" | "center" |
emptyThickness | Number | String | >=0 as Number or percent value as String | "5%" |
color | String | Object | any color as String or Object to specify gradient (see details) | "#3f79ff" |
colorFill | String | Object | same as color | "transparent" |
emptyColor | String | Object | same as color | "#e6e9f0" |
emptyColorFill | String | Object | same as color | "transparent" |
hideLegend | Boolean | true | |
legend | Number | String | any number, accepts a . or "," as decimals delimiter and simple formatting | |
legendFormatter | Function | Function that returns formatted value | |
animation | String | "default | rs | loop | reverse | bounce [duration delay]" | "default 1000 400" |
loading | Boolean | false | |
loader | Object | { [thickness, color, lineMode, line, opacity ]} | |
determinate | Boolean | false | |
noData | Boolean | false | |
angle | Number | any Number | -90 |
fontSize | String | any valid CSS value | "1rem" |
fontColor | String | any valid CSS value | "gray" |
legendClass | String | any | |
dash | String | "[strict] count spacing" | |
half | Boolean | false | |
gap | Number | any Number that defines the gap between multiple circles in pixel | 0 |
dot | String | Number | Object | Accepts size, color and other styles as Number, descriptive string "size [color]" or object {size [, backgroundColor, widht, borderRadius ...]} | 0 |
reverse | Boolean | false | |
data | Array | defines multiple circles, takes as values Objects with almost all props defined above |
progressIs any Number in range [-100, 100] (including decimals). This property defines the filled area from progress circle line in
percent and is shown by default as the legend in the middle of the circle. progress is animated and counts up or down on any value changes with duration defined in
animation.duration property. Set a negative value to fill the progress line counterclockwise. Alternatively reverse can be used.
<ve-progress :progress="myProgress" />
...
this.myProgress = 55.5;
this.myProgress = this.tasksDone * 100 / maxTasks; // the percentage of done tasks
ā The
progressis always used to fill the progress circle line, it should be always in the range [-100, 100] and not valid Numbers lead tonoDatastate. For customization purpose please uselegendand take a look atlegendFormatter.
ā If
legendis defined theprogresswill not be displayed as circle legend.
sizeIs any number >=0. It defines the width and height of the circle in pixel. The calculation of the circumference of the
circle depends on the properties lineMode, thickness,
emptyThickness and dot, so the circle never exceeds the size value!
ā Check
lineModeproperty to understand how the progress circle behaves depending on the line mode and offset.
lineIs a String value from round | square | butt. Defines the progress circle line cap. Internally the CSS property stroke-linecap is used.
<ve-progress line="round" />
thicknessIs a Number >=0 or a String that defines the progress line thickness. If you set the value in percent as String, the thickness will be calculated in relation to size.
<ve-progress :thickness="10" />
<ve-progress thickness="5%" />
emptyThicknessIs a Number >=0 or a String. It defines the empty circle line thickness. If you set the value in percent, thickness will be calculated in relation to size.
lineModeDescriptive string in form "mode [offset]" that defines, how the progress line is aligned in relation to empty line.
The first value ist the mode and the optional second is the offset. You can understand the modes as the presets that
help you to align lines as you want to.
mode:
center: this is the default value and both lines are aligned at the baseline (centered).
in: the progress line is inside the empty line
in-over: the progress line is both inside the empty circle and overlaps the empty line
out: the progress line is outside the empty line
out-over: the progress line is both outside the empty circle and overlaps the empty line
bottom: the progress line is aligned at the bottom of the empty line
top: the progress line is aligned at the top of the empty line
offset: is any negative or positive Number and defines the distance between the progress and empty lines. It can be only combined with the in and out modes
Let's take a look at few examples:
line-mode="in 10" | line-mode="in 10" | line-mode="out 10" | line-mode="out 15" |
|---|---|---|---|
 |  |  |  |
In general, any positioning can already be achieved with values in and out in a combination with certain offset. The modes, however, act like presets, which reduce the effort for the manual calculations.
linePositionDescriptive string in form "mode [offset]" that defines how the progress line is aligned in relation to the circle fill area.
Available modes are center, in and out. Additionally, with the out mode you can provide an offset value as any Number.
In general, this prop makes it possible to mimic the SVG2 stroke-aligment, which is currently not supported in any browser.
The following examples visualize the modes differences:
line-position="center" | line-position="out" | line-position="out 20" | line-position="in" |
|---|---|---|---|
 |  |  |  |
emptyLinePositionDescriptive string in form "mode [offset]" that defines how the empty line is aligned in relation to the empty circle fill area.
The usage is similar to linePosition.
colorDefines the color of progress circle line. Is any CSS color like #123 or lime or an object that defines the gradient.
color="#3f79ff" - as String
:color="{ colors [, radial ]}" - as Object
radial - default false. Boolean that defines, whether the gradient is radial or linearcolors - array that contains the gradient colors as objects { color: "#6546f7", offset: "10" [, opacity: 1] }<ve-progress :color="gradient" />
gradient: {
radial: false,
colors: [
{
color: '#6546f7',
offset: "0",
opacity: '1',
},
{
color: 'lime',
offset: "100",
opacity: '0.6',
},
]
}
colorFillDefines the fill color of the progress circle. Takes the same value as color
emptyColorDefines the color of the empty circle line. Takes the same value as color
emptyColorFillDefines the fill color of the empty circle. Takes the same value as color
hideLegendBoolean that defines whether the legend value (progress or legend) is hidden.
legendIs any Number or String. Use this property if you want to show the progress value as the legend of the circle that is not in
the range [-100, 100]. If defined, legend will replace progress as the circle legend! Defining the value as
string you can apply very simple formatting with "." or "," as delimiter to set initial counter placeholder (e.g "0045.00").
Apart from this the value must generally be a valid JavaScript Number. For more customization possibilities please
use legendFormatter or scoped slot.
Let's say you need to display a rating from 0 to 5 of a product with 3.5 stars. Setting the progress to 3.5 will
fill the circle to 3.5 percent, and this is not what we need, since we want to display the percentage of 5 as progress.
At this point we need an additional property legend. We can show the product rating like in the following example:
<ve-progress :progress="progress" :legend="rating" />
...
this.rating = 3.5;
this.progress = this.rating * 100 / 5; // the rating percentage
Now you can display custom progress value that still animated and circle progress fills properly!
<ve-progress legend="0100,450" /> // counts up from "0000,000"
ā note that
legendreplacesprogressas circle legend.
legendFormatterIs a Function that must return your custom formatted value. The function takes counter properties object as argument and is called on every counter tick. Here the formatting of legend or progress is completely up to you and you have the full freedom to adjust the presentation to your needs. The function can return any value, even HTML.
ā alternatively you can use
scoped slotfor custom formatting.
The function takes counter properties Object as argument that you can use to define custom formatting.
currentValue is the most relevant value, as it is the actual value at specific counter tick. The return value will be
displayed as the legend of the circle.
const myFormatter = ({ currentValue, ...otherProps }) => {
return new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(currentValue);
}
The function can also return HTML:
const myFormatter = ({ currentValue }) => {
return `
<span style="font-weight: bold; font-size: 1.6rem">${new Intl.NumberFormat("de-DE").format(currentValue)}</span>
<span>ā¬</span>
`;
}
Finally, set your formatter as prop:
<ve-progress :legend-formatter="myFormatter"/>
<!-- shorter version-->
<ve-progress :legend-formatter="({ currentValue }) => `My Format ${currentValue}`"/>
animationDescriptive string in form "type [duration delay]" that defines the initial animation of progress circle line filling. type is one from predefined animations and the optional duration and delay are Number values. Note that the order is important and that you can only define delay after duration.
type - is one of the predefined animations: default | rs | reverse | bounce| loopduration - number in milliseconds, default 1000delay - number in milliseconds, default 400animation="rs 700 200"
animation="bounce 1000"
loadingBoolean that forces loading state. The component provides an indeterminate loading state for the case that your data is not available immediately. With this property set to true you can use the component as the indeterminate progress.
loaderWith this option defined as Object you can customize the loading circle that is shown in the states
loading and determinate. Accepted properties are color, thickness, line,
lineMode, duration and opactity. duration and opacity are specific for loading circle.
Any valid CSS opacity value can be set as opacity. duration specifies the speed of the loader animation in milliseconds.
If the loader option is not specified, the loading circle replicates the progress circle with a 0.55 default value for opacity
and 1000 duration.
<ve-progress :loader="{ color: 'green', lineMode: 'in 10', opacity: '0.6', duration: 1500 }" />
determinateBoolean that provides a determinate loading state that indicates that your data loading is still in progress but allows to show the progress.
noDataBoolean that forces no data state. The component provides a no data state for the case that your data is not available. The circle progress is still empty.
ā The component will take the no data state even if you provide an invalid
progressvalue
angleIs any number. It defines the starting point of the progress circle line.
fontSizeIs any valid CSS size value. It defines the font size of the circle legend. You will have to use legendClass if you want to apply more specific styles.
fontColorIs any valid CSS color value. It defines the color of the circle legend. You will have to use legendClass if you want to apply more specific styles.
legendClassAdds class to the circles legend to give you the possibility to style it.
dashDescriptive string in form "[strict] count spacing" that adds dashed empty progress line. This property provides the optional strict mode. In this mode you can define the explicit number of dashes as count with the given relative spacing as number in range >= 0 and < 1. Without strict the default behavior of the SVG stroke-dasharray property is used, where the size and spacings of the dashes are defined.
<ve-progress dash="strict 60 0.5" /> - 60 dashes with 0.5 relative spacing
<ve-progress dash="10 10" /> - 10 pixels big dashes with 10 pixels spacing, the number of dashes depends on the empty circle circumference
halfBoolean that specifies the type of the circle. If it is set to true, only the half of the circle will be drawn.
<ve-progress half />
gapDefines the gap in pixels from one circle to the previous circle. It will be applied only if data prop is used.
<ve-progress :gap="10"/>
dotThe dot property lets you define a point indicator at the end of the progress line. You have a lot of freedom to customize the dot using a Number, descriptive String, or an Object to inject any CSS styles.
Number: :dot="10" - specifies a round dot with 10px width and height and default #713dfd color
Descriptive string: dot="size [color]" - size can be just a Number or a percent value like 5%, the calculation for percent values is similar to thickness and depends on the size. color is optional and lets you quickly define the color of the dot. The order of properties is important for parsing the String, and you can set the color only if the size is defined.
Object: :dot="{ size: Number | String [, any CSS inline style with Vue syntax] }" - to customize the point, you can define the prop as an Object. size is required and can be just a Number or a String to define a percent value. Only defining the prop as an Object you have the possibility to add any styles to the dot you want to, using Vue syntax for defining inline styles, you can even completely break the positioning of the dot, if you need. You cannot override the height of the dot since it is important for internal calculation and must be controllable.
The examples will provide more clarity
:dot="10" // just a Number defining size in pixel
dot="10" // the same as above
dot="10%" // 10% from the circle size will be converted to pixel
dot="5% red" // adds red dot
// defines same dot as above
:dot={
size: "5%", // required
backgroundColor: "red", // add any inline CSS using Vue syntax
left: "10px", // you can even move the dot, but it is not recommended
}
reverseIs a Boolean. reverse prop flips the circle, and the progress circle fills counterclockwise. Alternatively you can just set
a negative value for progress.
<ve-progress reverse />
dataYou can specify 2 or more circles as Objects in an array as data. For each circle you can use almost every available property. It is not necessary to specify all properties, they will be merged with global props, the specified props will overwrite the global. The circles are rendered inside each other.
ā Excluded props:
lineMode,emptyThickness,legend. These properties will be ignored, ifdatais specified. The legend of this circle is also not shown.
<!-- this props are applied to all circles, if not overwritten in "data"-->
<ve-progress color="blue" animation="loop 500" ... :data="data"/>
data: [
{
progress: 50, // required for each circle
color: "red", // will overwrite global progress color
... // other options will be merged with global
},
{
progress: 50, // required for each circle
animation: "rs 1500 500" // you can set almost any option that will be specific to this circle
}
}
defaultUse this scoped slot, if you want to customize the presentation of the circle legend and make a use of the animated counter,
so your formatting still animated. This works similar to the legendFormatter and is just
an alternative way to provide a custom format. You can access animated counter properties through the scoped slot
props and adjust the presentation of the legend to your needs.
<ve-progress :progress="50">
<template #default="{ counterTick }">
<span style="font-weight: bold; font-size: 1.6rem; color: green;">
{{ myFormatter(counterTick.currentValue) }}
</span>
</template>
</ve-progress>
legendIn this slot you can put an additional element that you want to display beside the progress
legend-captionIn this slot you can put any HTML and style it on your own. This slot is aligned below the progress.
This code ...
<ve-progress ....>
<template #legend>
<span>/200</span>
</template>
<template #legend-caption>
<p>TASKS DONE</p>
</template>
</ve-progress>
... produces following result. The slots are marked corresponding:
This project targets modern browsers, platforms and Vue frameworks. The SVG circles should be displayed without problems also in older browsers. The experience with some animations or transitions may vary slightly in different browsers.
 Edge |  Firefox |  Chrome |  Safari |  Opera |  Vivaldi |  Electron | Nuxt.js |
|---|---|---|---|---|---|---|---|
| :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
The development always happens in dev branch. You'll find all the latest updates there.
dev will only be merged into the master when all unit tests have been passed, builds are successful,
documentation is updated and functionality is verified on the demo page.
Before all that, changes remain in beta.
The project was initialized with Vue CLI. Execute the following commands to start development locally:
npm i
npm run serve
15 January 2022
885fbda561859c15c4b169d6e4ee74f40f11ccac17a35cc1e8bdbe4df19d30a6cf5f44b33dbd49044cf28c3f35c7f4b213564b78aad8918aFAQs
A Vue.js component to create beautiful animated circle progress bars
The npm package vue-ellipse-progress receives a total of 7,289 weekly downloads. As such, vue-ellipse-progress popularity was classified as popular.
We found that vue-ellipse-progress demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."