PullToRefresh

Controlled visual indicator for the pull-to-refresh interaction — the rotating arrow + label that appears at the top of a scrolling list as the user pulls.

This is the visual primitive only. The gesture (touch tracking, threshold detection, async refresh) is left to the consumer because that wiring is app-specific (router refresh, query invalidation, route reload). Drive the indicator by passing the current state.

Default#

Click the state buttons to flip through the four indicator states.

States#

Wiring the gesture#

Hook this up to touchstart / touchmove / touchend (or your preferred gesture lib) and translate the pull distance into the four states:

const [state, setState] = useState<PullToRefreshState>('idle');
 
const onTouchMove = (e) => {
  const delta = e.touches[0].clientY - startY;
  if (delta < 16) setState('idle');
  else if (delta < 80) setState('pulling');
  else setState('ready');
};
 
const onTouchEnd = async () => {
  if (state !== 'ready') return setState('idle');
  setState('loading');
  await refresh();
  setState('idle');
};

Props#