`circle-progress` 2.2.0

To take full control over the appearance of the circle progress, you can use the circle-progress slot. This scoped slot allows you to replace the default circle progress with any SVG or HTML content you want. The slot exposes all the (parsed) props passed to the component and also all necessary internal data to create default circle progress.

Experimental feature

This feature lets you sneak into the internals of the plugin and gives you a lot of power to customize the circle. It's challenging to provide good defaults for all possible use cases as you can place any content inside the slot. So you might encounter some strange inconsistencies in conjunction with other props. Basically, the slot just drops its content instead of the default circle progress and doesn't care much about how it fits into the rest of the component. Now it's up to you to make it look good.

Usage 📜

<ve-progress :progress="50">
  <template #circle-progress="{ attrs }">
    <circle
      :r="attrs.radius"
      :cx="attrs.position"
      :cy="attrs.position"
      fill="transparent"
      :stroke="attrs.color"
      :stroke-width="attrs.thickness"
      :stroke-linecap="attrs.line"
      :stroke-dasharray="attrs.circumference"
      :style="attrs.styles"
    >
    </circle>
  </template>
</ve-progress>

The attrs object contains all the necessary data to create a circle progress. Here a few important properties:

Property	Notes
`radius`	radius of the circle calculated depending on other props
`postion`	calculated position to place the circle correctly inside the SVG
`circumference`	the circumference (SVG path length) of the progress circle
`styles`	all the necessary styles to add smooth animations
`strokeDashOffset`	offset calculated based on the progress value, applicable only for circle elements like `<circle>` or `<ellipse>`
`calculateProgressOffset`	helper function accepting element path length to help you to calculate progress offset for SVG elements other than circle
`class` `animationClass`	Classes to apply animations

Inspect the attrs object to see all the available properties and their values. After the migration to TypeScript, the plugin will provide you with a better type definitions. The following examples will explain how and when to use these properties.

Slot recipe

Draw your SVG element inside the slot. If the element is not an ellipse-like element, you have to position it correctly by yourself.
Set the stroke-dasharray attribute to the path length of the SVG element. For the ellipse-like elements, you can use the attrs.circumference value.
Set the stroke-dashoffset attribute to the attrs.strokeDashOffset value for the ellipse-like elements. This value is calculated depending on the progress value. For other SVG elements, you can use the attrs.calculateProgressOffset(pathLength) function to calculate the progress offset.

Recreating the circle

First, we will recreate the default circle progress. I assume often you will use the slot to apply some custom styles or classes to the default circle progress. The plugin is optimized to show circular progress bars, so all the exposed properties in the attrs object are ready to be used to create a circle. The following example shows the exact SVG element that the plugin uses under the hood to create the default circle progress.

The same also can be done with the <ellipse> SVG element.

Beyond the circle

You can put anything inside the slot. There is no guarantee that the exposed properties will fit your SVG element. For example, the strokeDashOffset that "cuts" the circle line depending on the progress value is calculated depending on the circle circumference and therefore wouldn't work correctly for other SVG elements. The attrs.calculateProgressOffset helps you to calculate the progress offset for other SVG elements, with one caveat: you have to pass the path length of the element to the function.

Getting the path length

You can use svgElement.getTotalLength() to get the path length of the SVG element. In the future, this experimental feature might be improved to overcome this inconvenience.

Let's start with a simple example. Here we are drawing a polygon that still can show progress.

Warning

Pay attention to the behavior in different modes. In the modes loading and determinate the circle fallbacks to the default loader circle. In the future, you might get more control over this behavior.

Below are a few custom examples with SVG shapes taken directly from https://www.svgshapes.in.