expo-custom-refresh

Customizable pull-to-refresh for React Native lists. Use any React component as your refresh indicator: Lottie animations, skeleton loaders, branded spinners, or anything else.

Works with FlatList, FlashList, and ScrollView.

Why

React Native's built-in RefreshControl only renders the platform-default spinner. You can change its color, but you can't replace it with custom UI. This module gives you full control over what renders during pull-to-refresh, with native scroll physics on both platforms.

Install

npm install expo-custom-refresh

For bare React Native projects, run npx pod-install after installing.

Usage

import { CustomRefreshControl } from 'expo-custom-refresh';

function MyList() {
  const [refreshing, setRefreshing] = useState(false);

  const onRefresh = async () => {
    setRefreshing(true);
    await fetchData();
    setRefreshing(false);
  };

  return (
    <CustomRefreshControl
      refreshing={refreshing}
      onRefresh={onRefresh}
      renderIndicator={({ progress, state }) => (
        <MySpinner progress={progress} active={state === 'refreshing'} />
      )}
    >
      <FlatList data={items} renderItem={renderItem} />
    </CustomRefreshControl>
  );
}

The renderIndicator function receives:

• progress - A number from 0 to 1 representing how far the user has pulled
• state - One of 'idle', 'pulling', 'triggered', or 'refreshing'

Props

| Prop | Type | Default | Description | | ------------------ | ---------------------- | -------- | ----------------------------------------- | | refreshing | boolean | required | Whether a refresh is in progress | | onRefresh | () => void | required | Called when the user triggers a refresh | | renderIndicator | (props) => ReactNode | required | Render function for the refresh UI | | triggerThreshold | number | 80 | Pull distance (points) to trigger refresh | | indicatorHeight | number | 60 | Height of the indicator area |

Refresh states

| State | Description | | ------------ | -------------------------------------------------------- | | idle | No pull in progress | | pulling | User is pulling but hasn't reached the threshold | | triggered | User pulled past the threshold (will refresh on release) | | refreshing | Refresh is in progress |

Requirements

• Expo SDK 51+
• React Native 0.74+
• iOS 15.1+
• Android API 21+

License

MIT