# Circular Progress Bar

{% embed url="<https://youtu.be/kQia1fwLzg8?si=Z5juhmZMRlzXwh3h>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=kQia1fwLzg8>

The **Circular Progress Bar** widget visually represents the progress of an operation in a circular form.\
It can work in two modes:

* **Determinate** – shows actual progress (e.g., 35%, 70%, 100%).
* **Indeterminate** – shows an ongoing animation when the exact progress is unknown.

This widget is useful for loading states, uploads, background tasks, and any process where you want to keep the user informed.

#### Adding a Circular Progress Bar Widget

The Circular Progress Bar widget is located in the **Form Elements** section of the Widget Palette. Once added, you can configure its properties from the **Widget Properties Panel**.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-f339e2082a36f1761826eb3796c1fcd23b74922d%2Fcircular_progress_bar.gif?alt=media" alt="A hero image showing circular progress bars in different states and configurations."><figcaption><p>The Circular Progress Bar widget provides clear visual feedback for ongoing operations.</p></figcaption></figure>

### Core Concept

The Circular Progress Bar:

1. Draws a **circular track** (background circle).
2. Draws a **progress arc** (indicator) on top of it.
3. Uses the `type` property to decide how to behave:
   * **Determinate**: Uses `progressValue` (0–100) to show how much is completed.
   * **Indeterminate**: Ignores specific percentages and shows a continuous spinning or looping animation.

You can control:

* **How it looks** → `size`, `thickness`, `indicatorColor`, `bgColor`.
* **How it animates** → `animation`, `animateFromLastPercent`.
* **How it behaves** → `type`, `progressValue`.

### Properties

| Property                 | Description                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| `type`                   | The type of progress bar: `determinate` or `indeterminate`.                                               |
| `progressValue`          | The progress value for a determinate progress bar (from **0 to 100**). Ignored in `indeterminate` mode.   |
| `size`                   | The diameter of the circular progress bar. Controls how large the circle appears.                         |
| `thickness`              | The thickness of the circular progress bar’s stroke (the width of the progress ring).                     |
| `indicatorColor`         | The color of the progress indicator (the active part of the circle).                                      |
| `bgColor`                | The background color of the progress bar’s track (the inactive circular ring).                            |
| `animation`              | If `true`, changes in `progressValue` will be animated rather than jumping abruptly.                      |
| `animateFromLastPercent` | If `true`, the progress animation starts from the **previous** value and smoothly moves to the new value. |

{% hint style="success" %}
**Performance Tip:** Use `animateFromLastPercent` with `animation = true` for smooth progress transitions (e.g., 20 → 40 → 65%) instead of jerky jumps.
{% endhint %}

## Default Properties

The Circular Progress Bar widget supports all [default-properties](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").

### Use Cases

The **Circular Progress Bar** is used to show **loading or progress** in a compact, circular form.\
It works well when you don’t have much horizontal space or want a more **prominent, centered indicator**.

Use **Circular Progress Bar** for:

* **General Loading States**
  * Show a spinner while a screen, modal, or section is loading
  * Indicate background operations like login, verification, or fetching data
* **Inline Status Indicators**
  * Inside cards or tiles (e.g., progress of a single download/upload)
  * Next to a label or title to show something is still in progress
* **Percentage-Based Progress**
  * Show completion percentage for:
    * File upload/download
    * Backup/restore
    * Profile or setup completion
  * Often displayed in the center of the circle as a number or icon
* **Centered Focus**
  * Full-screen or modal loader in the center of the screen to show “please wait”
  * Highlight one key task’s progress in dashboards or detail pages