> 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/dynamic-components/components/progress-circle.md).

# Progress Circle

The Avonni Progress Circle component displays a circular indicator that shows completion toward a total, making it ideal for dashboards, KPI tracking, or any scenario where you want to visualise progress at a glance.

## Overview

The Progress Circle renders a ring that fills or drains as a value approaches its total. You can set the value directly as a static number, bind it to a Salesforce field, or have it computed from an aggregate query. A title and label can appear alongside the ring to give the number context.

## Configuration

To configure the Progress Circle, select it on the canvas. The configuration panel opens on the right. The sections below mirror the properties in panel order.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FSAy8EJ8kDt6OzSrnYqjN%2Fprogress-circle-builder-properties.png?alt=media" alt="The Edit Progress Circle panel showing Title, Label, Value, Total, Variant, Title Position and Size above the Advanced Options link" width="320"><figcaption><p>The Properties tab. <strong>Thickness</strong>, <strong>Direction</strong> and <strong>Alternative Text</strong> sit behind <strong>Advanced Options</strong>.</p></figcaption></figure>

### Properties

#### Title

Text displayed above or below the progress circle to introduce the metric being tracked. Use **Title Position** to place it at the top or bottom (default: **Bottom**).

#### Label

Text displayed after the value inside the ring — useful for adding a unit such as "%" or "pts".

#### Value

The current progress value. Enter a static number between 0 and 100 when tracking a simple percentage, or switch to Query mode to calculate the value from a Salesforce aggregate (SUM, COUNT, AVG, MIN, or MAX of a chosen field). In query mode you can also supply a SOQL filter expression to restrict which records contribute to the value.

#### Total

The number that represents 100 % completion (default: **100**). Change this when your value is not already a percentage — for example, set Total to 500 if your value is a raw record count. Like Value, Total supports Query mode with its own SOQL filter expression.

#### Variant

Controls whether the numeric value is shown inside the ring.

| Option                 | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| **Standard** (default) | The current value is displayed in the centre of the ring. |
| **Value Hidden**       | The ring fills without showing a number inside.           |

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FDnE4XIFQlqgWCK2WTYJq%2Fprogress-circle-variant.png?alt=media" alt="Two progress circles at 68 percent, one showing the value in the middle and one with the middle empty"><figcaption><p>The same value in both. <strong>Value Hidden</strong> keeps the ring and the label and drops the number.</p></figcaption></figure>

#### Title Position

Where the title text appears relative to the ring. Options: **Top**, **Bottom** (default).

#### Size

Overall diameter of the progress circle. Options: **X-Small**, **Small**, **Medium** (default), **Large**, **X-Large**.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FlziyaRGrLh0zLQQefr8S%2Fprogress-circle-size.png?alt=media" alt="Five progress circles at 68 percent, growing from x-small to x-large"><figcaption><p>The five diameters. The value and label scale with the ring.</p></figcaption></figure>

#### Thickness

Width of the ring stroke. Options: **X-Small**, **Small**, **Medium** (default), **Large**, **X-Large**. Available in **Advanced** options.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FOUxh1xFqePgDEp4UqhEZ%2Fprogress-circle-thickness.png?alt=media" alt="Five progress circles of the same diameter with the ring stroke growing from x-small to x-large"><figcaption><p>The five stroke widths at the same <strong>Size</strong>. The diameter does not change.</p></figcaption></figure>

#### Direction

Controls which way the colour flows from the top of the ring.

| Option             | Description                                              |
| ------------------ | -------------------------------------------------------- |
| **Fill** (default) | The ring fills clockwise as the value increases.         |
| **Drain**          | The ring drains counterclockwise as the value increases. |

Available in **Advanced** options.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FFv1lpc7OI3nNsaWs4ZoF%2Fprogress-circle-direction.png?alt=media" alt="Two progress circles at 35 percent, one filled clockwise from the top and one filled counterclockwise from the top"><figcaption><p>The same 35 percent. <strong>Fill</strong> runs clockwise from the top, <strong>Drain</strong> runs counterclockwise.</p></figcaption></figure>

#### Alternative Text

Accessible description of the component, announced to screen readers in place of the visual indicator. Available in **Advanced** options.

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Output Variables

The Progress Circle exposes this output variable you can reference elsewhere on the page after the component renders.

### Progress State

| Output variable | Type   | What it returns                                                     |
| --------------- | ------ | ------------------------------------------------------------------- |
| **Percentage**  | Number | The current progress value expressed as a number between 0 and 100. |

> **Example:** Place a text component beside the Progress Circle and bind its content to **Percentage** to display the exact completion figure next to the ring.

## Styling

Configure the Progress Circle's appearance from the **Style** tab of the Edit Progress Circle panel.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the component.

* **Top / Right / Bottom / Left:** Adjust the space on each side.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing around the component.

* **Top / Right / Bottom / Left:** Adjust the space on each side.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the component.

* **Color / Size / Style / Radius:** Set the border color, thickness, style, and corner rounding.
  {% endtab %}

{% tab title="Bar" %}
Styles the progress ring.

* **Background Color:** Set the unfilled track color.
* **Color:** Set the filled progress color.
  {% endtab %}

{% tab title="Value" %}
Styles the percentage value in the center.

* **Color / Font Style / Font Weight:** Set the value color and typography.
  {% endtab %}

{% tab title="Title" %}
Styles the title text.

* **Color / Font Style / Font Weight / Line Clamp:** Set the title color, typography, and line clamp.
  {% endtab %}

{% tab title="Label" %}
Styles the label text.

* **Color / Font Style / Font Weight:** Set the label color and typography.
  {% endtab %}
  {% endtabs %}


---

# 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/dynamic-components/components/progress-circle.md?ask=<question>&goal=<endgoal>
```

`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.