> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/progress-circle.md).
# 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.
```html
```
**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.
```html
```
**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 for assistance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/progress-circle.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.