Refresh Indicator

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.

The Refresh Indicator widget provides pull-to-refresh functionality for scrollable content.

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.