RefreshControl: The Pull-to-Refresh Handler

WHY IT EXISTS Mobile users expect to be able to pull down on a list to get the latest data. RefreshControl provides this standard UI pattern, connecting a common gesture to an app-specific data-fetching action without developers having to build the gesture detection and animation from scratch.

THE MENTAL MODEL Think of RefreshControl as a controlled component, like a text input. You provide its current state (the 'refreshing' prop) and a function to call when the user interacts with it (the 'onRefresh' callback). The component itself doesn't fetch data; it just tells you when to fetch data and shows a spinner while you tell it to.

HOW IT WORKS You pass an instance of RefreshControl to the refreshControl prop of a ScrollView or FlatList. When the user pulls the list down from the very top, the component's onRefresh callback is triggered. Inside this callback, you must immediately set a state variable that controls the refreshing prop to true. Then, you start your data fetching logic. Once the data fetch completes, you set that same state variable back to false to hide the spinner.

WHEN TO USE IT Use RefreshControl inside any ScrollView, FlatList, or SectionList where users need to manually trigger a content update. This is the standard UI for social media feeds, news lists, dashboards, or any list of data that can change on the server.

WHEN NOT TO USE IT Do not use it for non-scrollable content, as the pull gesture won't be available. It is also not a substitute for real-time updates (like WebSockets) if your application requires instant data synchronization without user interaction. RefreshControl is for user-initiated actions only.

ONE CANONICAL EXAMPLE The most common footgun is misunderstanding the refreshing prop. It's a controlled prop. You must have a state variable, say isRefreshing, that you pass to it. Your onRefresh handler must call setIsRefreshing(true) at the very beginning. Then, after your async data fetching operation is complete, you must call setIsRefreshing(false). If you forget to set it to true, the refresh indicator will appear and disappear immediately, before your data has a chance to load.