A modern pull-to-refresh controller that lets you drop in any GIF/APNG/Lottie (or static image) as the refresh indicator. Map pull progress to animation frames, trigger a looping “loading” state, and finish with a success check—delivering fun, brandable reloads with zero UI jank on real devices.

Functionality

• Pull-down gesture with configurable threshold, resistance, and overscroll

• Plug-and-play GIF/APNG/Lottie indicator with progress → frame mapping

• States: pull, armed, loading (loop), success/error with snap-back

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

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

• Optional “Last updated” label and haptic feedback on trigger/complete

• Error handling: toast/snackbar messaging + Retry callback

• Works with ListView, GridView, CustomScrollView/Slivers, nested scrolls

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

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

• Theming: size, placement, margins, colors, background blur/shadow

• Dark/light mode, RTL/localization, and reduce-motion support

• High-performance rendering; real-device tested at 60fps targets

Use cases

• News/social feeds that benefit from branded GIF loaders

• E-commerce lists refreshing inventory/prices with playful indicators

• Media galleries and travel apps using themed stickers or Lottie

• Dashboards refreshing KPIs/cards with status-aware animations

• Community/chat timelines re-syncing latest items

• Campaign or seasonal refreshers (holiday/event-themed GIFs)

• Offline apps exposing cached → fresh data on demand

Keywords
pull to refresh, swipe to refresh, refresh control, GIF indicator, APNG, Lottie animation, custom loader, progress mapping, elastic overscroll, success checkmark, error state, retry action, debounce, throttle, timeout, single flight, programmatic refresh, refresh API, last updated label, haptic feedback, infinite scroll, pagination, cache then network, SWR pattern, slivers, list view, grid view, nested scroll, theming, dark mode, reduce motion, RTL support, high performance, 60fps, Flutter widget, FlutterFlow component, mobile web, branded loader, animated sticker.