flutter_custom_refresh_indicator

The CustomRefreshIndicator widget allows you to build highly customized pull-to-refresh animations. It wraps a scrollable widget (like ListView) and provides an IndicatorBuilder to render your custom UI based on the current scroll progress and state.

To use it, you must provide:

1. child: The scrollable widget.
2. onRefresh: An AsyncCallback that performs the refresh logic.
3. builder: A function that takes the BuildContext, the child, and an IndicatorController to build your indicator widget.

By default, the widget automatically rebuilds whenever the controller's state or value changes (controlled by the autoRebuild parameter).

CustomRefreshIndicator(
  onRefresh: () async {
    // Perform refresh logic here
    await Future.delayed(Duration(seconds: 2));
  },
  builder: (context, child, controller) {
    return Stack(
      children: [
        child,
        // Use controller.value (0.0 to 1.5) to drive animations
        Positioned(
          top: controller.value * 50,
          child: CircularProgressIndicator(),
        ),
      ],
    );
  },
  child: ListView.builder(
    itemCount: 20,
    itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
  ),
)

Use the onStateChanged callback in CustomRefreshIndicator to execute logic when the indicator transitions between different states (e.g., from dragging to armed). The callback provides an IndicatorStateChange object which includes a didChange method to check for specific transitions.

Common use cases include playing sounds, triggering animations, or resetting UI elements when the indicator returns to the idle state.

CustomRefreshIndicator(
  onRefresh: onRefresh,
  // Track state changes with the onStateChanged callback.
  onStateChanged: (IndicatorStateChange change) {
    // When transitioning from dragging to armed state, do something:
    if (change.didChange(from: IndicatorState.dragging, to: IndicatorState.armed)) {
      // Handle the armed state, e.g., play a sound, start an animation, etc.
    }
    // When returning to the idle state from any other state, do something else:
    else if (change.didChange(to: IndicatorState.idle)) {
      // Reset any animations, update UI elements, etc.
    }
  },
)

The CustomRefreshIndicator widget accepts several parameters to control its behavior, timing, and appearance:

Basic

• child (Widget): The scrollable content (e.g., ListView).
• builder (IndicatorBuilder): Function returning the indicator widget.
• onRefresh (AsyncCallback): The logic to execute when refresh is triggered. Must return a Future.
• controller (IndicatorController?): Manages state and interaction.

Timing and Durations (RefreshIndicatorDurations)

• cancelDuration: Duration to hide the indicator after canceling.
• settleDuration: Duration for the indicator to settle after release.
• finalizeDuration: Duration to hide the indicator after refreshing.
• completeDuration: (Optional) How long the indicator stays in the complete state after onRefresh finishes. If omitted, it skips complete and goes straight to finalizing.

Trigger Behavior

• offsetToArmed (double?): Pixel distance required to trigger refresh.
• containerExtentPercentageToArmed (double?): Percentage of container extent required to arm.
• trigger (IndicatorTrigger): Defines which edge (leading, trailing, or both) triggers the refresh.
• triggerMode (IndicatorTriggerMode): Configures the condition for triggering.

Other

• onStateChanged (OnStateChanged?): Callback when the indicator state changes.
• notificationPredicate (ScrollNotificationPredicate): Determines which ScrollNotifications trigger the indicator.
• leadingScrollIndicatorVisible (bool): Visibility of the leading indicator.
• trailingScrollIndicatorVisible (bool): Visibility of the trailing indicator.
• autoRebuild (bool): Whether to automatically rebuild the indicator on controller updates.

The IndicatorController provides real-time access to the indicator's current status, position, and movement details. This is essential for building highly customized UI that reacts to the user's physical drag actions.

Core Properties

• state (IndicatorState): The current lifecycle state of the indicator.
• edge (IndicatorEdge?): Which end the gesture started from (start or end). Useful when trigger is set to bothEdges.
• side (IndicatorSide): Where the indicator is positioned (top, bottom, left, right, or none).
• direction (AxisDirection): The axis direction of the scrollable content.
• scrollingDirection (ScrollDirection): The current direction the user is scrolling.
• dragDetails (DragUpdateDetails?): Detailed pointer information during a drag.

dragDetails Sub-properties

When dragDetails is available, you can access:

• globalPosition: The global pointer position.
• delta: The distance moved since the last update.
• primaryDelta: The distance moved along the primary axis (e.g., vertical movement in a vertical list).

Use the RefreshIndicatorDurations class to customize the timing of different animation phases in the refresh indicator. This allows you to control how quickly the indicator cancels, settles into a loading state, or finalizes after a refresh is complete.

Available Durations

const durations = RefreshIndicatorDurations(
  cancelDuration: Duration(milliseconds: 500),
  settleDuration: Duration(milliseconds: 200),
  finalizeDuration: Duration(milliseconds: 150),
  completeDuration: Duration(seconds: 1),
);

The CustomMaterialIndicator widget replicates the standard Material refresh indicator behavior but allows for extensive customization of its appearance, displacement, and container properties.

You can use the default constructor for a standard Material look or the .adaptive() constructor to automatically switch between CupertinoActivityIndicator (iOS/macOS) and RefreshProgressIndicator (Android/others) based on the platform.

Key customization options include:

• displacement: The distance from the edge where the indicator settles.
• edgeOffset: The offset where the indicator starts to appear on drag.
• indicatorBuilder: A function to provide a custom widget for the indicator.
• scrollableBuilder: A builder to construct the scrollable widget (e.g., a ListView).

CustomMaterialIndicator(
  onRefresh: () async {
    // Your refresh logic here
  },
  child: ListView.builder(
    itemCount: 20,
    itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
  ),
);