Pull to refresh is one component with ten props, and seven of them only work on one platform.

Which component does React Native give you for this?

RefreshControl, and only that one. It sits in the core components list next to Pressable and ScrollView, and its reference page opens by saying the component is used inside a ScrollView to add pull to refresh functionality, and that when the scroll position is at zero, swiping down fires an onRefresh event. That second half matters more than it looks. The gesture only exists at the top of the content, so somebody halfway down a long list cannot set it off by accident while scrolling, and you do not have to write a rule to stop them.

Two props carry the whole interaction. refreshing is a boolean and it is the only prop on the page the reference marks as required: it says whether the view should currently be indicating an active refresh. onRefresh is a function and it runs when the view starts refreshing. The component also inherits View props, which is how you get style, testID and the accessibility props on it without them being listed again.

One wrinkle worth knowing before you go looking for it. The opening sentence of that reference page names ScrollView or ListView as the two places this component goes, and ListView is not in the current list of components. The Core Components and APIs page, which carries its own last updated date of 10 September 2026, gives RefreshControl a one line summary that names only ScrollView, and the word ListView appears nowhere on it. Read the older sentence as a ScrollView or anything built on top of one, which in practice means every list React Native ships.

React Native, RefreshControl reference, version 0.87, last updated 12 August 2026, read 22 October 2026

Which of its props work on iOS, and which on Android?

Three props work on both platforms, three are badged iOS and four are badged Android. The badges are printed as text on the reference page rather than as icons, so the split is unambiguous. The table below is that page, reorganised so you can see the asymmetry in one look rather than by scrolling past ten headings.

Three consequences come out of that table, and each one has caught somebody. The first is the label. A line of text under the spinner, the thing people use for a last updated time, exists only on iOS through title and titleColor. There is no Android counterpart listed, so if you want that line on both platforms it belongs in your own layout above the first row, where you control it anyway.

The second is turning the gesture off. enabled does precisely that and defaults to true, and it is badged Android only. On iOS there is no documented prop for it, so you either stop passing a refresh handler or you leave the control out of the render for that state. It is a conditional instead of a prop, and it behaves the same on both platforms, which is usually the version you want in the code anyway.

The third is colour. iOS gives you one tintColor for the spinner. Android gives you colors, which is an array needing at least one entry, plus progressBackgroundColor for the disc behind it and size for a choice between a default and a large indicator. If your design has one brand colour, pass it as tintColor on iOS and as a one entry array on Android and the two will match. If the design has a gradient or a sequence, only Android can express it.

React Native, RefreshControl props, ten props with seven platform badges, read 22 October 2026

Does it work inside every scrollable, or only some?

Only vertical ones, and the documentation says so twice in two different places. The ScrollView reference has a single prop for this, refreshControl, which takes a RefreshControl element and whose description ends by saying it only works for vertical ScrollViews and that the horizontal prop must be false. ScrollView lists no onRefresh and no refreshing of its own, so on a plain ScrollView you build the element yourself and hand it to that prop. That page carries its own last updated date of 14 October 2026.

Lists work differently and more conveniently. VirtualizedList, which is the engine under the lists you actually use, documents onRefresh and refreshing directly: provide a handler and the reference says a standard RefreshControl is added for pull to refresh, with a reminder to set the refreshing prop correctly. FlatList inherits VirtualizedList props, in those words on its own page, and SectionList is documented as a convenience wrapper around VirtualizedList that also inherits ScrollView props. So the same two props cover all three, and both list pages carried a last updated date of 19 October 2026 when they were read.

That leaves the cases where it does not work at all. Horizontal is the big one: ScrollView describes horizontal as arranging children in a row instead of a column, it defaults to false, and setting it true puts you outside what refreshControl supports. VirtualizedList repeats the restriction for itself. A sideways carousel has no top edge to pull away from, so a refresh there needs a button or a timer instead. If your list is long enough that refreshing the top is only half the problem, the other half is in add infinite scroll.

React Native, VirtualizedList reference, last updated 12 August 2026, read 22 October 2026

Why does the spinner stop before the data arrives?

Because refreshing is a controlled prop, and the reference page says it in a note rather than in the prop table, which is why it gets missed. The indicator is visible while that boolean is true and gone when it is false. If onRefresh fires a request and nothing sets the flag, the indicator stops as soon as your finger leaves the screen. The note spells out the fix: set it to true inside the onRefresh function. Set it false when the work finishes, and set it false on the failure path too, because a dropped request with no error handler leaves a spinner turning until the user force quits.

The second failure is quieter and harder to spot. If you pass refreshControl to a list and also pass onRefresh and refreshing, the list uses your element and ignores both props. The VirtualizedList reference states it plainly: a custom refresh control overrides the control built internally, and onRefresh and refreshing are also ignored. Nothing warns you. The gesture works, the spinner appears, and your handler never runs. Pick one of the two approaches per list and delete the other, rather than keeping both and hoping.

The third is cosmetic until somebody screenshots it. A translucent or sticky header will sit on top of the indicator, and the prop for that is progressViewOffset, a number with a default of 0 and no platform badge. The SectionList page gives the concrete version, offsetting the control from the top by 100 points, and the FlatList page describes the same prop as the one to set when an offset is needed for the loading indicator to show correctly. Reach for it before you reach for padding on the list, because padding moves the content as well.

One last thing that is not in the documentation because it is not a prop. Decide what a refresh means in your app before you wire it up. Refetching the first page of a list is the common case. Refetching the first page while the user has unsaved input on the screen is a data loss bug wearing a gesture, and it shows up in forms more than lists, which is the same class of problem described in add form validation.

React Native, VirtualizedList refreshControl prop, on overriding the built-in control, read 22 October 2026

What this looks like in an app you did not hand write

It looks the same, if the thing you generated is a real project. Newly writes a React Native and Expo codebase that you own, with two-way GitHub sync, so the list on your screen is a React Native list with props you can read and change. Pull to refresh is two props and a piece of state in that file, which means you can ask for it in plain English or add it yourself afterwards without either route being a dead end. It is $25 a month and there is no free tier.

This is the practical reason to care whether a builder hands you source. A gesture like this one is a small change to a list component, and in a project you own it stays a small change. In a product that renders your screens from a configuration you cannot reach, it is a feature request. The difference only shows up on the second or third thing you want to adjust, which is late enough to be expensive.

Newly uploads iOS builds to TestFlight, publishes to Google Play internal testing and builds a standalone Android APK, so the refresh you just added is testable on a real device the same day. It does not press submit on the App Store for you, because Apple requires the owner of the content to submit, and that step with its own requirements is covered in publish to app store.