vue-ellipse-progress

A Vue.js component to create beautiful animated circular progress bars

❕ ❕ ❕ Live interactive DEMO here ❕ ❕ ❕

How to use

install the library via npm

npm i -S vue-ellipse-progress

The library is provided as a Vue.js plugin. So just initialize it in your main.js

import VueEllipseProgress from 'vue-ellipse-progress';

Vue.use(VueEllipseProgress);

Now use the component

<vue-ellipse-progress 
  :progress="progress"
  :angle="-90"
  color="blue"
  :colorFill="colorFillGradient"
  emptyColor="#8ec5fc"
  :emptyColorFill="emptyColorFillGradient"                      
  :size="300"
  :thickness="10"
  emptyThickness="10%"
  :lineMode="{mode: 'in', offset: 10}"
  :legend="true"
  :legendValue="180"
  legendClass="legend-custom-style"
  :dash="{count: 60, spacing: 0.9}"
  :animation="{type: 'reverse', duration: 700, delay: 400}"
  :noData="false"
  :loading="false"                      
  fontColor="white"
  :half="false"                      
  fontSize="5rem">
  
  <span slot="legend-value">/200</span>
  <p slot="legend-caption">GOOD JOB</p>
  
</vue-ellipse-progress>

Options

Actually you are ready to go with only following line:

<vue-ellipse-progress :progress="progress"/>

The progress is the only one required property. However in order to created unique circles that match your design needs you can use all the properties explained below.

This table provide a quick overview over all available options. For more information and how to create exclusive circles using this properties please read below the table.

❕ Also make sure to check slot options

• progress

Animated: ✔️

is any Number from 0 to 100 (including decimals). This property defines the filled area from progress circle line in percent. progress is animated and count up or down on any value changes with duration defined in animation:duration property. How the progress is calculated is up to you. The progress is shown by default as the legend in the middle of the circle.

Example: 📜

this.progress = 55.5;
this.progress = this.tasksDone * 100 / maxTasks; // the percentage of done tasks

❗ the progress is always used to fill the progress circle line. So you can not customize this value and all values under 0 and above 100 are ignored. For customization purpose please use legendValue. if legendValue is defined the progress is NOT displayed as circle legend.

• size

Animated: ✔️

is any Number from >=0. Defines the width and height of the circle. The circumference of the circle is calculated depending on the properties lineMode, thickness and emptyThickness so the progress circle never exceeds the size value!

❗ check lineMode property to understand how the progress circle behaves depending on the line mode and offset.

• line

is a string value from round | square | butt. Defines the progress circle line cap. Internaly is used the css property stroke-linecap.

• thickness

Animated: ✔️

is any Number or percent value >=0. Defines the progress circle line thickness. If you define the value in percent the thickness will be calculated in relation to size. Internaly is used the css property stroke-width.

• lineMode

Animated: ✔️

This property defines how the progress line is aligned in relation to empty line. You can undestand the modes as the preset that helps you to easy align lines as you need.

• mode:

  • normal: this is the default value and both lines are aligned at the base line (centered).

    

  • in: the progress line is inside the empty circle

    

  • in-over: the progress line is also inside the empty circle but overlap the empty circle

    

  • out: the progress line is outside the empty circle

    

  • out-over: the progress line is also outside the empty circle but overlap the empty circle

    

  • bottom: the progress line is aligned at the bottom of the empty circle

    

  • top: the progress line is aligned at the top of the empty circle

    

• offset: is any negative o positive number and defines the distance between the progress and empty lines. Can be only combied with the in and out modes

Example: 📜

Lets take a look at few examples

{mode: 'in', offset: 10}	{mode: 'in', offset: -10}	{mode: 'out', offset: 10}	{mode: 'out', offset: -15}

As you can see the second and fourth examples are similar to the modes bottom and top. Only with the modes in and out and the offset you can achive the same result. But the povided modes like a presets take care about annoying calculations and do the job for you. Make sure to play with this values in the demo!

• emptyThickness

Animated: ✔️

is any Number or percent value >=0. Defines the empty circle line thickness. If you define the value in percent thickness will be calculated in relation to size. Internaly is used the css property stroke-width.

• color

Defines the color of progress circle line. Is any css color like #123 or lime or an object that defines the gradient.

• color: (String) '#3f79ff'

• color: (Object)

  • gradient: (Object) defines the gradient
    • radial default false. Defines whether the gradient is radial or linear
    • colors: (Array) contains the gradient colors as an object {color: "#6546f7", offset: 0, opacity: 1}

Example: 📜

Now you are ready for a bad example.

{
      {
        radial: false,
        colors;: [
          {
            color: '#6546f7',
            offset: '0',
            opacity: '1',
          },
          {
            color: 'lime',
            offset: '100',
            opacity: '1',
          },
        ],
      },
    },

• colorFill

defines the fill color of the progress circle. Takes the same value as color

• emptyColor

defines the color of the empty circle line. Takes the same value as color

• emptyColorFill

defines the fill color of the empty circle. Takes the same value as color

• legend

is a Boolean. Defines whether the progress or from you defined legendValue is displayd as the legend of the circle.

• legendValue

Animated: ✔️

is any Number. Use this property if you want to customize the shown progress as the legend of the circle. If defined legendValue replaces progress as the circle legend!

Example: 📜

Lets say you have to display a rating from 0 to 5 of a product with 3.5 stars. Since progress can take values only from 0 to 100 your need an additionall property legendValue. Now you can set legendValue = 3.5 and calculate the progress something like that:

this.progress = 3.5 * 100 / 5; // the rating percentage

Now you can display custom progress value that still animated and circle progress fills properly!

❗ note that legendValue excludes progress but not vice versa.

• animation

defines the initial animation of progress circle line filling. You can choose one from predefined animations and set a specific duration and delay.

• type:
  • default | rs | reverse | bounce| loop try this animations in the demo!
• duration Number in milliseconds, default 1000
• delay Number in milliseconds, default 400

Example: 📜

:animation="{type: 'rs', duration: 700, duration: 200}"

• loading

forces loading state. The component provide an indeterminate state for the case that you data is not available immediately. With this property set true you can use the component as the indeterminate progress.

• noData

forces no data state. The component provides an no data state for the case that you data is not available. The circle progress still empty.

❗ the component takes the no data state also if you provide an invalid progress value

• angle

is any Number. Defines the starting point of the progress circle line

• fontSize

is any valid css size property. Defines the font size of the circle legend. Use legendClass if you want apply more specific styles

• fontColor

is any valid css color. Defines the color of the circle legend. Use legendClass if you want apply more specific styles

• legendClass

adds class to the circles legend to give you the possibility to style it

• dash

Animated: ✔️

is string or object. Internaly is used the value stroke-dasharray so if you define the value as string you can specify the size and the spacing of the dashes. For more precise dashes calculations you can define the value as an object with explicit number of dashes and spacing.

Example: 📜

dash="10 10" - as String with 10px big dashes and 10px spacing. Or just dash="10"

:dash="{;
    60; // Number of dashes
    0.99; // spacing between dashes, any value >= 0 and < 1
  }"

• half

boolean value that specifies the type of the circle. If set to true only the half of the circle is drawn like a gague chart

Example: 📜

Slot options

• legend-value

in this slot you can put an additionall element that you want to display biside the progress

• legend-caption

in this slot you can put any HTML and slye it on your own. This slot is aligned below the progress

Example: 📜

This code ...

<vue-ellipse-progress ....>
  
    <span slot="legend-value">/200</span>
    <p slot="legend-caption">TASKS DONE</p>
  
</vue-ellipse-progress>

... produces following result. The slots are marked corresponding:

Compatibility

The plugin was tested in all major modern browsers. Should also work properly in older browsers. In old browsers issues can be caused by animations since they are implemented using css custom properties. Basic svg renders even in IE 11.

Edge	Firefox	Chrome	Safari	Opera	Vivaldi	Electron	Nuxt.js
✅	✅	✅	✅	✅	✅	✅	✅

Development

npm install

Compiles and hot-reloads

npm run serve

Build for publishing

npm run lint
npm run test:unit
npm run build