react-native-custom-refresh/ReadMe.md

react-native-custom-refresh is a highly customizable pull-to-refresh component for React Native, built with Reanimated 2. It provides smooth pull-to-refresh animations with a rotating loader and customizable header text or components. Supports both user-i

# 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

```bash
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:

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

---


## Usage

Wrap your scrollable content inside `ReanimatedRefresh` and provide necessary props:

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

---