Progress Circle

avonni-progress-circle

Displays progress or a value as a circular indicator with a customizable label.

Overview

Progress Circle is a Lightning Web Component that displays a percentage value as a circular ring with a centered numeric readout.

Use it in your own Lightning Web Components to visualize completion, scores, or any 0–100 metric at a glance. You control the value, size, ring thickness, fill direction, title placement, and an optional indeterminate loading animation—all through the component's attributes.

Use Cases

• Task completion: Show how far along a record, checklist, or job is.
• KPI dashboards: Surface a percentage metric in a compact, glanceable form.
• Quotas and goals: Visualize progress toward a target.
• Storage or capacity: Indicate how much of a limit has been used.
• Loading states: Use the loading animation while a value is being fetched.

---

Size Guidelines

Size	Use Case
xx-small / x-small	Inline with text or in dense list rows.
small / medium	Cards and standard dashboard tiles.
large and up	Hero metrics and prominent KPI displays.

---

Use Case Examples

Example 1: Task completion indicator

Scenario: Show how far a project has progressed at the top of a custom record page component.

<!-- projectProgress.html -->
<template>
    <avonni-progress-circle
        alternative-text="Project 65% complete"
        title="Completion"
        title-position="top"
        value="65"
        label="%"
        size="large"
    ></avonni-progress-circle>
</template>

Result: A large ring filled clockwise to 65%, showing "65%" in the center with "Completion" above it.

Example 2: Loading state while fetching a value

Scenario: Display an indeterminate animation while a metric is being retrieved, then render the real value once it arrives.

<!-- liveScore.html -->
<template>
    <avonni-progress-circle
        alternative-text="Loading score"
        title="Score"
        value={score}
        is-loading={loading}
        size="medium"
    ></avonni-progress-circle>
</template>

Result: While loading is true, the ring animates and hides the value; once loading is false, it shows the resolved score.

---

Specifications

Attributes

Name	Description	Type	Default	Required
alternative-text	The assistive text for the progress circle.	String	—
direction	Controls which way the color flows from the top of the ring, either clockwise or counterclockwise Valid values include fill and drain. The fill value corresponds to a color flow in the clockwise direction. The drain value indicates a color flow in the counterclockwise direction.	String	"fill"
is-loading	If present the progress bar displays a loading animation. The value goes from 0 to 100 repeatedly and the label displays a 3 dots animation. The value and labels become hidden.	Boolean	false
label	The label is displayed after the value in the progress circle.	String	—
size	The size of the progress circle. Valid values include xx-small (26x26px), 'x-small' (40x40px), small (52x52px), medium (104x104px), large (152x152px) and x-large (208x208px).	String	"medium"
thickness	Set progress circle thickness. Valid values include x-small, small, medium, large and x-large.	String	"medium"
title	The title is displayed at the bottom or top of the progress circle.	String	—
title-position	Position of the title. Valid values include top and bottom.	String	"bottom"
value	The percentage value of the progress circle. The value must be a number from 0 to 100. A value of 50 corresponds to a color fill of half the ring in a clockwise or counterclockwise direction, depending on the direction attribute.	Number	0
variant	Accepted variants include standard, value-hidden.	String	"standard"

Styling Hooks

CSS Variable	Type	Default
--avonni-progress-circle-bar-color-background	color	#dddbda
--avonni-progress-circle-bar-color	color	#0176d3
--avonni-progress-circle-bar-content-color-background	color	#ffffff
--avonni-progress-circle-value-text-color	color	#0176d3
--avonni-progress-circle-value-font-style	font	normal
--avonni-progress-circle-value-font-weight	font	400
--avonni-progress-circle-title-text-color	color	#080707
--avonni-progress-circle-title-font-family	font	—
--avonni-progress-circle-title-font-size	font	—
--avonni-progress-circle-title-font-style	font	normal
--avonni-progress-circle-title-font-weight	font	400
--avonni-progress-circle-title-line-clamp	number	3
--avonni-progress-circle-title-line-height	dimension	—
--avonni-progress-circle-title-letter-spacing	dimension	—
--avonni-progress-circle-label-text-color	color	#706e6b
--avonni-progress-circle-label-font-style	font	normal
--avonni-progress-circle-label-font-weight	font	400
--avonni-progress-circle-label-font-size	font	xx-small:10px | x-small:10px | small:11px | medium:12px | large:14px | x-large:16px
--avonni-progress-circle-label-line-clamp	number	2
--avonni-progress-circle-value-font-size	font	—

Key Considerations

• Value range: Values are clamped to 0–100; pass a normalized percentage.
• Direction: fill flows clockwise, drain flows counterclockwise from the top of the ring.
• Loading: When is-loading is true, the value and label are hidden in favor of the animation.
• Hidden value: Use the value-hidden variant to show the ring fill without the numeric readout.
• Accessibility: Provide alternative-text so the progress is announced.
• Best Practice: Keep value within 0–100 and set alternative-text so screen readers can announce the progress.

---

Troubleshooting Common Issues

• Ring not filling: Confirm value is a number between 0 and 100, not a string fraction.
• Value not showing: Check that is-loading is not true and variant is not value-hidden.
• Title in the wrong place: Set title-position to top or bottom.
• If issues persist: Contact our support team at [email protected] for assistance.