Pull to refresh

Installation

$ npx shadcn@latest add https://goodui.dev/native/r/pull-to-refresh.json

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated, react-native-svg match your Expo SDK. Files land in components/goodui-native/pull-to-refresh.

Usage

import { PullToRefresh } from "@/components/goodui-native/pull-to-refresh/pull-to-refresh";

export function Inbox() {
  const { messages, reload } = useMessages();
  return (
    <PullToRefresh onRefresh={reload} contentContainerStyle={{ padding: 16, gap: 8 }}>
      {messages.map((m) => (
        <MessageRow key={m.id} message={m} />
      ))}
    </PullToRefresh>
  );
}

When to use

Examples

<PullToRefresh
  tone="accent"
  onRefresh={() => api.syncOrders()}
  labels={{ success: "Orders synced", error: "Sync failed" }}
>
  {orders}
</PullToRefresh>

<PullToRefresh refreshing={isSyncing} onRefresh={sync}>{content}</PullToRefresh>

API reference

Motion and haptics

• •The content follows the finger with growing resistance; the drop in the gap stretches with the pull.
• •Passing the threshold snaps the drop round on the bouncy spring and turns its arrow upward; pulling back un-arms it on the snappy spring.
• •Releasing armed holds the content open on the smooth spring while a spinner runs; the result shows a drawn check or an alert for 750 ms, then everything tucks away.
• •Reduced motion: the drop never stretches or bounces, the arrow flips, and settling uses a short timing curve instead of a spring.

• •Haptic: tap when the pull passes the threshold (configurable with the haptic prop)
• •Haptic: success when onRefresh resolves, error when it rejects

• •The pull, the drop and the content offset run on the UI thread; React renders only when the state changes (armed, refreshing, result).
• •The spinner shows for at least 450 ms, so a fast refresh never flashes.

Accessibility

• •With a screen reader on, a Refresh button appears at the top of the content on every platform, so nobody has to perform the pull gesture.
• •The scroll view reports busy while refreshing; the result is announced with the success or error label.
• •The indicator itself is hidden from screen readers.
• •On the web the refresh strip is named by its visible text and Enter or Space refreshes.

Notes for AI

Related