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. |