A highly-tunable pull-to-refresh controller with iOS-style spinners, elastic drop/wave animations, and horizontal refresh indicators for edge gestures. Designed for real feeds at scale, V4 adds more parameters, safer concurrency, and programmatic refresh—delivering silky, haptic reloads without UI jank.

Functionality

• Natural pull-down gesture with threshold, resistance, and overscroll tuning

• Indicator presets: iOS spinner, arrow→spinner morph, drop/wave, Lottie, custom builder

• Horizontal refresh indicator for side-pull patterns (e.g., tab/content carousels)

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

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

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

• “Last updated” label, success checkmark, and optional toast/snackbar errors

• Works with ListView, GridView, Slivers, NestedScrollView, pinned app bars

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

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

• Theming: colors, sizes, indicator position, shadow, corner radius, typography

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

• Dark/light mode, safe-area aware (notch/status bar), RTL/localization

• Real-device tested performance; 60fps targets with virtualization

Use cases

• News/social feeds that need fast manual reloads

• E-commerce category pages refreshing inventory or prices

• Dashboards updating KPIs, charts, and cards in place

• Messaging/activity timelines re-syncing latest items

• Media libraries (albums/playlists) fetching new content

• Booking/search results after filter or location changes

• Admin/CMS tables that requery without navigation

• Offline apps exposing cached → fresh data on demand

Keywords
pull to refresh, swipe to refresh, refresh control, iOS spinner, elastic wave, drop indicator, horizontal refresh, side pull, arrow morph, success checkmark, last updated label, debounce, throttle, timeout, single flight, programmatic refresh, refresh API, error state, retry action, optimistic UI, cache then network, SWR pattern, infinite scroll, pagination, slivers, list view, grid view, nested scroll, safe area, dark mode, haptic feedback, reduce motion, accessibility, RTL support, theming, high performance, Flutter widget, FlutterFlow component, mobile web, smooth animation, real device tested.