Skip to main content
Version: 2.x (Next)

Pull to refresh

Pull to refresh is tricky with collapsible headers. The header is overlayed on top of the scroll content, and the content itself is offset — so the refresh indicator needs to account for the header height to appear in the right place.

Header Motion supports two refresh modes:

  • React Native-compatible refresh, where Header Motion adjusts progressViewOffset for the built-in RefreshControl.
  • Headless refresh, where HeaderMotion.RefreshControl triggers refresh behavior and exposes progress through useRefreshControl() so your header can render the UI.

Usage​

Pass refreshing and onRefresh props directly to the scrollable, just like you would with a regular ScrollView or FlatList:

const [isRefreshing, setIsRefreshing] = useState(false);

const handleRefresh = () => {
setIsRefreshing(true);
fetchData().finally(() => setIsRefreshing(false));
};

<HeaderMotion.ScrollView refreshing={isRefreshing} onRefresh={handleRefresh}>
{/* content */}
</HeaderMotion.ScrollView>;

You can also pass an explicit RefreshControl component if you need more control over its styling:

<HeaderMotion.ScrollView
refreshControl={
<RefreshControl refreshing={isRefreshing} onRefresh={onRefresh} />
}
>
{/* content */}
</HeaderMotion.ScrollView>

Headless refresh UI​

Use HeaderMotion.RefreshControl when you want to render the refresh indicator yourself, usually inside the header:

const [isRefreshing, setIsRefreshing] = useState(false);

const handleRefresh = () => {
setIsRefreshing(true);
fetchData().finally(() => setIsRefreshing(false));
};

<HeaderMotion.ScrollView
refreshControl={
<HeaderMotion.RefreshControl
refreshing={isRefreshing}
onRefresh={handleRefresh}
/>
}
>
{/* content */}
</HeaderMotion.ScrollView>;

Then read the refresh state anywhere inside the same HeaderMotion tree:

import { useRefreshControl } from 'react-native-header-motion';
import { useAnimatedStyle } from 'react-native-reanimated';

const refresh = useRefreshControl();

const style = useAnimatedStyle(() => ({
opacity: Math.min(refresh.progress.get(), 1),
transform: [{ scale: 0.8 + Math.min(refresh.progress.get(), 1) * 0.2 }],
}));

The exposed state includes the UI-ready progress, advanced rawProgress, pullDistance, triggerDistance, phase, overshoot, and convenience booleans like isReady, isRefreshing, isSettling, and isActive. See useRefreshControl for the full state reference, including how progress differs from rawProgress.

Use progressCommitDuration to tune how quickly overshoot visually snaps back to committed refresh progress, and progressSettleDuration to tune the return to idle.

If onRefresh fires but you never set refreshing={true}, the control settles back to idle after refreshConfirmationTimeout milliseconds (default 200). Pass 0 or a negative value to disable this fallback — the control then stays in the Refreshing phase until you toggle refreshing, like React Native's built-in refresh controls. Pull gestures stay blocked for as long as that phase lasts, so with the fallback disabled every onRefresh must eventually flip refreshing back to false.

triggerDistance is measured against the damped pull distance the control reports, not against how far the finger moved: iOS reads the scroll view's rubber-banded overscroll and Android applies a 0.5 drag rate on top of the touch slop. Expect the same value to feel different per platform and tune it on-device.

One refresh state per HeaderMotion

The refresh state lives in the HeaderMotion context, because its intended consumer is the header. All refresh controls inside one HeaderMotion share that single state — independent simultaneous refresh controls are deliberately not supported. In tab or pager setups this is what you want: the header keeps showing the active refresh even if the user switches tabs mid-refresh.

Platform notes​

Native code

HeaderMotion.RefreshControl contains native code. After you install or update the library, rebuild the app. For iOS, run pod install before the build. With Expo, use a development build. Expo Go does not include this native control.

info

Built-in Android refresh works well with the adjusted progressViewOffset.

For fully custom refresh UI, prefer HeaderMotion.RefreshControl. It does not render a native spinner.

Using with ScrollManager​

If you're using ScrollManager directly instead of a pre-built scrollable, pass the refresh-related props (refreshing, onRefresh, or refreshControl) to ScrollManager itself — not to the inner scrollable component.

What's next?​

Learn how to make the header react to overscrolling in Overscroll.