# 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-e27bd3b13b12e47c3a217a8b8d5ea0a1df67c904%2Frefresh_indicator.gif?alt=media" 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.