Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



Version published
Weekly downloads
decreased by-17.65%
Weekly downloads



1.0.36 (2024-06-10)

  • Updated README



Progress Ring Component

test npm version Published on Built With Stencil

This is an animated web component showing progress in percentage. It internally uses easing-animation-frames library to create CPU-friendly easing animations and compiled with Stencil.

  1. Demo 1
  2. Demo 2
  3. Demo 3

How to use

Demo 1

<progress-ring percentage="30"></progress-ring>
<progress-ring percentage="60" round-linecap="true"></progress-ring>
<progress-ring percentage="90" disable-digits="true">
  <p class="completed-count">9/10<br />Complete</p>

There is only one mandatory property, percentage, which declares the ending percentage in animation. You can also use radius prop to change the size of the ring, and storkeWidth to change the thickness of the ring. The full list of properties can be found below.

You can also place custom HTML elements within the component's <progress-ring></<progress-ring> tag as HTMLSlotElement, which you have full control on for styling.

This component works reactively in a unidirectional fashion. When the percentage changes, it stops the current animation and resumes it with new percentage. There is pre-defined color scheme (red (< 25%) -> yellow (< 50%) -> blue (< 75%) -> green (>= 75%)).

Demo 2

<progress-ring percentage="10"></progress-ring>

<div class="buttons">
  <button id="buttonOne">30%</button>
  <button id="buttonTwo">60%</button>
  <button id="buttonThree">90%</button>

  const ring = document.querySelector("progress-ring");
  const buttonOne = document.querySelector("#buttonOne");
  const buttonTwo = document.querySelector("#buttonTwo");
  const buttonThree = document.querySelector("#buttonThree");

  buttonOne.addEventListener("click", () => {
    ring.setAttribute("percentage", 30);
  buttonTwo.addEventListener("click", () => {
    ring.setAttribute("percentage", 60);
  buttonThree.addEventListener("click", () => {
    ring.setAttribute("percentage", 90);


percentagenumber0Percentage value (mandatory)
radiusnumber80Radius of the ring
stroke-widthnumber10Thickness of the ring
round-linecapbooleanfalseAddes rounded linecap to the ring
durationnumber4000Animation duration in miliseconds
easing-typestring"quartInOut"Easing animation function name
int-sizenumber30Font size of integer
decimal-sizenumberintSize * 0.7Font size of decimals
disable-digitsbooleanfalseHides digits
disable-decimalsbooleanfalseHides decimal places
colorsstring'[[0,"#ff4f40"],[25, "#ffcd40"],[50, "#66a0ff"],[75, "#30bf7a"]]'Color steps with percentage and color code
invert-colorsbooleanfalseInverts the color scheme
event-idstringundefinedEvent Id to be used for animation callbacks
Easing Types

Easing Types refer to Robert Penner's Easing Function names: backInOut, backIn, backOut, bounceInOut, bounceIn, bounceOut, circInOut, circIn, circOut, cubicInOut, cubicIn, cubicOut, elasticInOut, elasticIn, elasticOut, expoInOut, expoIn, expoOut, linear, quadInOut, quadIn, quadOut, quartInOut, quartIn, quartOut, quintInOut, quintIn, quintOut, sineInOut, sineIn and sineOut.

Advanced usage with animation events

By passing even-id as a prop, you can listen to events emitted by with the animation, and register callback functions for them. Please see Demo 3.

Demo 3

Event NamePayloadDescription
prcProgress{ id: string, progress: number, percentage: number }Event to be emitted on every progress change (from 0 to 1)
prcColor{ id: string, color: string }Event to be emitted for the color value
prcStart{ id: string }Event to be emitted when the animation starts
prcComplete{ id: string }Event to be emitted when the animation is completed
prcStop{ id: string }Event to be emitted when the animation is stopped
prcResume{ id: string }Event to be emitted when the animation is resumed
prcRestart{ id: string }Event to be emitted when the animation is restarted

You can either directly import the component in script tag or integrate it into the framework you're using for the project.

How to load in your project

Simply place a script tag <script type="module" src=""></script> in the head of your index.html.

<!DOCTYPE html>
    <progress-ring percentage="50"></progress-ring>

If you're using Typescript, you may need additional types. The example below is a React component.

import { JSX as LocalJSX } from "progress-ring-component/loader";
import { HTMLAttributes } from "react";

type StencilToReact<T> = {
  [P in keyof T]?: T[P] &
    Omit<HTMLAttributes<Element>, "className"> & {
      class?: string;

declare global {
  export namespace JSX {
    interface IntrinsicElements
      extends StencilToReact<LocalJSX.IntrinsicElements> {}

function App() {
  return (
      <progress-ring percentage={30}></progress-ring>

export default App;



Last updated on 10 Jun 2024

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.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc