Pull to refresh

Problem Context

• The surface is a feed, inbox, notification center, activity list, dashboard, timeline, or status list where users expect newer server data.
• The content already scrolls vertically, and the refresh gesture begins only when the relevant scroll container is at its top boundary.
• The same content may also support nested scrolling, search filters, pagination, offline cache, live updates, load-more, or retry after failure.
• Users may interact through touch, mouse, keyboard, switch control, screen reader, external keyboard, D-pad, or assistive pointer devices.

Selection Rules

• Choose pull to refresh when the design problem is the vertical top-of-scroll drag that refreshes the current data set.
• Use touch gesture when the question is the broader gesture vocabulary, threshold, feedback, and fallback contract across many touch actions.
• Use feed, activity feed, notification center, dashboard layout, or list view when the primary problem is stream structure, ordering, unread state, filtering, or content comprehension.
• Use loading spinner or progress bar when the question is status display for a running operation rather than the user gesture that starts refresh.
• Use offline state when connection loss changes what data is available, and show pull-to-refresh failure or disabled refresh as one state inside that offline contract.
• Use retry when a known refresh request failed and the user is reattempting that same failed request outside the pull gesture.
• Trigger only when the user pulls downward from the beginning of the intended scroll container; do not fire from the middle of a list or inside the wrong nested scroller.
• Provide an equivalent manual refresh action in the toolbar, overflow menu, command menu, or visible control.
• Do not use pull-to-refresh for destructive, reset, submit, payment, account, security, or consent actions.
• Do not replace pagination, live update controls, or stale-data labeling with a hidden gesture.

Required States

• Idle state with current content visible and last updated timestamp when freshness matters.
• Scrolled-not-at-top state where upward scroll does not arm refresh.
• At-top armed state that can begin measuring downward pull distance.
• Pulling-under-threshold state with progress feedback and no request started.
• Threshold reached state with Release to refresh copy.
• Refreshing state with one in-flight refresh, disabled duplicate activation, and status message.
• Success state with refreshed content, stable scroll or focus, and updated timestamp.
• No-new-data state that confirms the refresh completed without changing the list.
• Failed refresh state that preserves existing content and offers retry or manual refresh.
• Offline or cached-data state that labels stale content and avoids endless spinning.
• Nested scroll state where inner content scrolls before the outer refresh container arms.
• Rate-limited or cooldown state with wait reason and next possible refresh time.
• Manual refresh equivalent state reachable without the gesture.
• Mobile compact and large-text states where indicator, controls, and status do not overlap.

Interaction Contract

• Pull-to-refresh begins only when the intended scroll container is at its top boundary and the user drags downward beyond normal scroll tolerance.
• The indicator shows progress toward a defined threshold before refresh starts.
• The refresh request starts on release after threshold, not merely on touch down or incidental overscroll.
• Releasing before threshold cancels the gesture and leaves data unchanged.
• Only one refresh runs per data scope at a time; duplicate pulls, manual refresh, and automatic refresh share the same in-flight guard.
• Existing content stays visible during refresh unless the product has a stronger reason to switch to a separate loading state.
• The result announces refreshing, refreshed, no new updates, failed, offline, or rate limited through visible text and programmatic status.
• Nested scroll containers define which scroller owns the gesture before implementation.

Implementation Checklist

• Name the data scope refreshed by the gesture, such as current inbox filter, current feed, selected workspace, or current dashboard cards.
• Detect the top of the intended scroll container and exclude middle-of-list, horizontal swipe, row action, text selection, drag handle, and nested-scroll gestures.
• Set pull distance, threshold, release boundary, cancel behavior, indicator placement, and in-flight duplicate guard.
• Make the manual refresh control call the same refresh method as the pull gesture.
• Preserve scroll anchor, selected item, focus target, filters, read state, expanded rows, and cached data across the refresh.
• Show last updated, refreshing, refreshed, no new updates, failed, offline, retry, and rate-limited states near the affected content.
• Use status messaging so assistive technology can perceive refresh start and result without moving focus unexpectedly.
• Test top-of-scroll detection, nested scrollers, slow network, offline mode, rate limits, duplicate pulls, large text, screen reader, keyboard, switch, mouse wheel, touchpad, and mobile landscape.

Common Generated-UI Mistakes

• Making pull-to-refresh the only way to update the data.
• Triggering refresh from anywhere in the list instead of only from the top of the intended scroll container.
• Providing no pull distance, threshold, release-to-refresh, refreshing, success, failure, or last-updated feedback.
• Clearing existing content during refresh and making the surface feel like a full page reload.
• Letting nested comment panels, maps, carousels, or row actions fight the refresh gesture.
• Starting duplicate refresh requests while one is already in progress.
• Spinning forever while offline or rate limited.
• Using the gesture for hidden reset, delete, submit, or destructive effects.

Critique Questions

• Which exact scroll container owns the pull, and how do you know it is at the top?
• What pull distance and threshold tell users when release will refresh?
• What visible and announced status proves refreshing started, succeeded, found no new data, failed, or was blocked offline?
• Where is the equivalent manual refresh path for users who cannot or do not perform the gesture?
• What happens to scroll position, focus, selected item, filters, and cached content while refresh runs?
• How do nested scrollers, horizontal row actions, touch gesture shortcuts, and browser or OS gestures avoid conflicts?
• What prevents duplicate refresh, rate-limit loops, and destructive side effects?