# Refresh Indicator

{% embed url="<https://youtu.be/CrVFhq-ysl8?si=a8qPBbmDUVR24WN5>" %}

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

The **Refresh Indicator** widget is used to trigger a **pull-to-refresh** action on scrollable content.\
When the user drags down from the top of a list or scroll view, a refresh spinner appears and an action (like an API call) is executed.

<figure><img src="/files/0Az7sqQJffaUdk1wRKIX" alt="A hero image showing a refresh indicator with pull-to-refresh animation on a mobile screen." height="300"><figcaption><p>The Refresh Indicator widget provides pull-to-refresh functionality for scrollable content.</p></figcaption></figure>

### Core Concepts

1. **Pull-to-Refresh Gesture**
   * The user **pulls down** at the top of a scrollable area.
   * When a threshold is reached, the **refresh action** is triggered (typically an API call or data reload).
2. **Loading Feedback**
   * A **spinner/indicator** is shown while the refresh is in progress.
   * Once the action completes, the indicator hides and the updated content is shown.
3. **Scroll Integration**
   * The Refresh Indicator usually wraps a **scrollable widget** (like a list or scroll view).
   * It listens to scroll gestures and only activates when the user is **at the top** of the content.
4. **Idempotent Action**
   * The refresh action is generally **safe to run multiple times** (re-fetch data, reload state) without breaking the UI, making it a friendly, repeatable user affordance.

### **Properties**

| Property           | Description                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `Show Indicator`   | Controls whether the refresh indicator is visible when a refresh is triggered.                  |
| `Color`            | The color of the progress indicator.                                                            |
| `Background Color` | The background color of the progress indicator.                                                 |
| `Displacement`     | The distance from the edge of the screen to the center of the progress indicator.               |
| `Edge Offset`      | The distance from the edge of the screen where the refresh indicator can be triggered.          |
| `Stroke Width`     | The thickness of the circular progress indicator's line.                                        |
| `Trigger Mode`     | How the refresh indicator is triggered. `onEdge` triggers it when the user pulls from the edge. |
| `On Refresh`       | The action to be executed when the user triggers a refresh.                                     |

### Child of Refresh Indicator

| Slot    | Description                                                                                                                        |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `child` | The single child widget that contains the scrollable content (like a ListView or ScrollView) that the refresh indicator will wrap. |

### Default Properties

The Refresh Indicator widget does not have the standard default properties. Its behavior is primarily controlled by the properties listed above.

### Use Cases

Use **Refresh Indicator** when you want the user to:

* **Manually refresh data**
  * Update a product list, feed, or timeline
  * Refresh notifications, messages, or activity logs
  * Reload dashboard stats or reports
* **Recover from stale or failed data**
  * Let users retry after an error by pulling to refresh
  * Give control when auto-refresh is not enough or not desired

Anywhere you show **scrollable, data-driven content** (ListView, GridView, Smart Scroll View, etc.), adding a Refresh Indicator improves the experience.


---

# Agent Instructions: 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:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/scrolling-widgets/refresh-indicator.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.