react-native-custom-refresh

react-native-custom-refresh

react-native-custom-refresh is a fully customizable pull-to-refresh component for React Native, built with Reanimated 2. It provides smooth pull-to-refresh animations with a rotating loader and supports custom header text or components. It works with both manual user gestures and programmatic refresh triggers.

Features

• Smooth pull-to-refresh animation using Reanimated 2
• Rotating and scaling loader with custom image support
• Default or custom text/component for header
• Programmatic refresh via the refresh prop
• Configurable maximum pull distance and trigger fraction
• Works with nested scroll views using PanResponder
• Fully customizable styles

Installation

npm install react-native-custom-refresh-control
# or
yarn add react-native-custom-refresh-control

Peer Dependencies

This library requires react-native-reanimated as a peer dependency. Make sure it is installed:

npm install react-native-reanimated
# or
yarn add react-native-reanimated

Usage

Wrap your scrollable content inside ReanimatedRefresh and provide necessary props:

import React, { useState } from "react";
import { View, Text } from "react-native";
import ReanimatedRefresh from "react-native-custom-refresh-control";

const Example = () => {
  const [refreshing, setRefreshing] = useState(false);

  const fetchData = async () => {
    setRefreshing(true);
    // Simulate API call or async operation
    await new Promise((resolve) => setTimeout(resolve, 2000));
    setRefreshing(false);
  };

  return (
    <ReanimatedRefresh
      refresh={refreshing}
      onRefresh={fetchData}
      maxPull={150}
      triggerFraction={0.5}
      headerText="Loading..."
      textComponent={
        <Text style={{ color: "purple", fontWeight: "700" }}>
          Refreshing...
        </Text>
      }
    >
      <View
        style={{
          height: 1000,
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        <Text>Scroll me to refresh!</Text>
      </View>
    </ReanimatedRefresh>
  );
};

export default Example;

Props

Prop	Type	Default	Description
onRefresh	() => Promise<void>	—	Callback fired when refresh is triggered.
maxPull	number	150	Maximum pull distance to trigger refresh.
triggerFraction	number	0.5	Fraction of maxPull to trigger refresh.
gradientColors	string[]	['#FF6A00', '#EE0979', '#FF6A00']	Gradient colors for masked text (optional).
loaderSource	ImageSource	Default loader.png	Custom loader image.
headerText	string	'Loading'	Default text displayed during refresh.
textComponent	ReactNode	Default <Text> with headerText	Custom component for header text.
style	object	{}	Custom style for the root container.
refresh	boolean	false	External trigger for programmatic refresh.