Light Dark System
Get ready for more awesome! Web Awesome, the next iteration of Shoelace, is on Kickstarter. Read Our Story

Progress Ring

<sl-progress-ring> | SlProgressRing
Since 2.0 stable

Progress rings are used to show the progress of a determinate operation in a circular fashion. 

<sl-progress-ring value="25"></sl-progress-ring>

import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';

const App = () => <SlProgressRing value="25" />;

Examples

Size

Use the --size custom property to set the diameter of the progress ring.

<sl-progress-ring value="50" style="--size: 200px;"></sl-progress-ring>

import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';

const App = () => <SlProgressRing value="50" style={{ '--size': '200px' }} />;

Track and Indicator Width

Use the --track-width and --indicator-width custom properties to set the width of the progress ring’s track and indicator. 

<sl-progress-ring value="50" style="--track-width: 6px; --indicator-width: 12px;"></sl-progress-ring>

import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';

const App = () => <SlProgressRing value="50" style={{ '--track-width': '6px', '--indicator-width': '12px' }} />;

Colors

To change the color, use the --track-color and --indicator-color custom properties. 

<sl-progress-ring
  value="50"
  style="
    --track-color: pink;
    --indicator-color: deeppink;
  "
></sl-progress-ring>

import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';

const App = () => (
  <SlProgressRing
    value="50"
    style={{
      '--track-color': 'pink',
      '--indicator-color': 'deeppink'
    }}
  />
);

Labels

Use the label attribute to label the progress ring and tell assistive devices how to announce it. 

<sl-progress-ring value="50" label="Upload progress"></sl-progress-ring>

import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';

const App = () => <SlProgressRing value="50" label="Upload progress" />;

Showing Values

Use the default slot to show a label inside the progress ring.

50% 
<sl-progress-ring value="50" class="progress-ring-values" style="margin-bottom: .5rem;">50%</sl-progress-ring>

<br />

<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>

<script>
  const progressRing = document.querySelector('.progress-ring-values');
  const subtractButton = progressRing.nextElementSibling.nextElementSibling;
  const addButton = subtractButton.nextElementSibling;

  addButton.addEventListener('click', () => {
    const value = Math.min(100, progressRing.value + 10);
    progressRing.value = value;
    progressRing.textContent = `${value}%`;
  });

  subtractButton.addEventListener('click', () => {
    const value = Math.max(0, progressRing.value - 10);
    progressRing.value = value;
    progressRing.textContent = `${value}%`;
  });
</script>

import { useState } from 'react';
import SlButton from '@shoelace-style/shoelace/dist/react/button';
import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';

const App = () => {
  const [value, setValue] = useState(50);

  function adjustValue(amount) {
    let newValue = value + amount;
    if (newValue < 0) newValue = 0;
    if (newValue > 100) newValue = 100;
    setValue(newValue);
  }

  return (
    <>
      <SlProgressRing value={value} style={{ marginBottom: '.5rem' }}>
        {value}%
      </SlProgressRing>

      <br />

      <SlButton circle onClick={() => adjustValue(-10)}>
        <SlIcon name="dash" label="Decrease" />
      </SlButton>

      <SlButton circle onClick={() => adjustValue(10)}>
        <SlIcon name="plus" label="Increase" />
      </SlButton>
    </>
  );
};

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.17.1/cdn/components/progress-ring/progress-ring.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.17.1/cdn/components/progress-ring/progress-ring.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/progress-ring/progress-ring.js';

To import this component as a React component:

import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';

Slots

Name Description
(default) A label to show inside the ring.

Learn more about using slots.

Properties

Name Description Reflects Type Default
value The current progress as a percentage, 0 to 100. number 0
label A custom label for assistive devices. string ''
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Custom Properties

Name Description Default
--size The diameter of the progress ring (cannot be a percentage).
--track-width The width of the track.
--track-color The color of the track.
--indicator-width The width of the indicator. Defaults to the track width.
--indicator-color The color of the indicator.
--indicator-transition-duration The duration of the indicator’s transition when the value changes.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.
label The progress ring label.

Learn more about customizing CSS parts.