A gesture-driven refresh control with a liquid, curved top header that stretches as you pull, then snaps into a loading state and finishes with a smooth reset. Safe-area aware and delightfully tactile, it provides clear feedback without covering content—perfect for modern feeds and galleries.

Functionality

• Natural pull-down gesture with configurable threshold and resistance

• Animated wave/arc header that morphs with pull progress

• States: pull → armed → loading → success/error with snap-back

• Inline spinner/Lottie/icon inside the header (optional)

• Haptic feedback on trigger and completion

• Programmatic API: refresh(), complete(), fail(), reset()

• Debounce/throttle, timeout, and single-flight guard (no duplicate calls)

• Optional “Last updated” label and auto-dismiss success checkmark

• Works with ListView, GridView, Slivers, NestedScrollView

• Plays nicely with infinite scroll (top refresh + bottom load more)

• Offline-first ready (cache → revalidate / SWR) with optimistic hooks

• Safe-area/notch aware; supports translucent app bars

• Theming: header height/curve, colors, indicator size/position, shadows

• Accessibility: semantics, large hit targets, reduce-motion support

• RTL & localization-ready text; dark/light mode

Use cases

• Social/news feeds needing quick manual reloads

• E-commerce lists refreshing inventory or prices

• Photo/video galleries fetching latest items

• Dashboards reloading KPIs, cards, and charts

• Messaging or activity timelines re-syncing recent updates

• Booking/search results after filter or location changes

• Admin/CMS tables requiring in-place requery

• Offline apps exposing cached → fresh data on demand

Keywords
pull to refresh, elastic wave, curved header, liquid indicator, wave morph, overscroll, refresh control, loading spinner, success checkmark, last updated label, programmatic refresh, single flight, debounce, throttle, timeout, safe area, notch aware, slivers, list view, grid view, nested scroll, infinite scroll compatible, optimistic UI, SWR pattern, cache then network, haptic feedback, reduce motion, accessibility, localization, RTL support, dark mode, theming, 60fps, smooth animation, Flutter widget, FlutterFlow component, mobile web, high performance, modern UI.