rn-fade-wrapper/README.md

🔥 Fade gradient wrapper for React Native scrollable views and overlays on iOS and Android.

# React Native fade gradient wrapper

<p align="center">
  <img src="./assets/img.png" width="700" alt="React Native fade gradient wrapper demo" />
</p>

**`rn-fade-wrapper`** is a simple, highly-performant React Native component that adds smooth, customizable **fade gradients** to the edges of any content. Perfect for enhancing the user experience in scrollable containers, lists, carousels, modals, or any view with overflowing content.

<div align="center" style="max-width: 400px; margin: auto;">
  <a href="https://www.npmjs.com/package/rn-fade-wrapper">
    <img src="https://img.shields.io/npm/v/rn-fade-wrapper.svg" alt="npm version" />
  </a>
  <img src="https://img.shields.io/badge/platform-iOS-blue?logo=apple" alt="iOS" />
  <img src="https://img.shields.io/badge/platform-Android-green?logo=android" alt="Android" />
  <img src="https://img.shields.io/badge/Expo-supported-9B59B6?logo=expo" alt="Expo" />
  <img src="https://img.shields.io/badge/types-TypeScript-blue?logo=typescript" alt="TypeScript" />
  <img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT License" />
  <a href="https://bundlephobia.com/result?p=rn-fade-wrapper">
    <img src="https://img.shields.io/bundlephobia/minzip/rn-fade-wrapper" alt="Bundle size" />
  </a>
</div>

---

## ✨ Features

- ⚡ Native rendering for **iOS** and **Android**
- 🔁 Supports **vertical** and **horizontal** gradient directions
- 🎨 Fully **customizable fade size and color** (per side or uniform)
- ↕️ Optional `inward` mode to fade **towards content** instead of outward
- 🧩 Simple API: drop-in wrapper with intuitive props
- 💪 Great performance — gradients are rendered natively, ideal for scroll views and animations
- 🔧 Works in **bare React Native** and **Expo** (EAS Build / Development Build)

---

## 📦 Installation

```bash
yarn add rn-fade-wrapper
# or
npm install rn-fade-wrapper
```

### Bare React Native

Autolinking handles everything. No extra steps needed.

### Expo

This library uses native code and requires a [Development Build](https://docs.expo.dev/develop/development-builds/introduction/) or EAS Build. **It does not work in Expo Go.**

1. Add the plugin to your `app.json`:

```json
{
  "expo": {
    "plugins": ["rn-fade-wrapper"]
  }
}
```

2. Rebuild your native project:

```bash
npx expo prebuild
# or use EAS Build
eas build
```

---

## 📱 Platform Support

| Platform | Old Architecture | New Architecture (Fabric) |
|----------|:----------------:|:-------------------------:|
| iOS      | ✅               | ✅                        |
| Android  | ✅               | ✅                        |

---

## 🚀 Quick Start

```tsx
import { FadeWrapper } from 'rn-fade-wrapper';

const MyComponent = () => {
  return (
    <FadeWrapper color="#ffffff" size={24} orientation="vertical">
      <ScrollView>
        <Text>Fading edges example</Text>
      </ScrollView>
    </FadeWrapper>
  );
};
```

---

## 🧩 Props

| Prop          | Type                                                                 | Default      | Description |
|---------------|----------------------------------------------------------------------|--------------|-------------|
| `color`       | `string`                                                             | white        | Fade color — any valid color string (`"#fff"`, `"rgba(0,0,0,0.5)"`, etc.) |
| `size`        | `number`                                                             | `20`         | Uniform fade size in points, applied according to `orientation` |
| `orientation` | `'horizontal' \| 'vertical'`                                        | `'vertical'` | Applies `size` to top/bottom (`vertical`) or left/right (`horizontal`) |
| `sizes`       | `{ top?: number, right?: number, bottom?: number, left?: number }`  | —            | Per-edge fade sizes. **Takes precedence** over `size` and `orientation` |
| `inward`      | `boolean`                                                            | `false`      | Flips the gradient direction — fades inward (towards the center of the content) |
| `style`       | `ViewStyle`                                                          | —            | Additional style for the wrapper view |
| `children`    | `React.ReactNode`                                                    | —            | Content to wrap |

---

## 🎛 Examples

### Vertical scroll fade (default)

```tsx
<FadeWrapper color="#ffffff" size={32}>
  <ScrollView>
    {/* content */}
  </ScrollView>
</FadeWrapper>
```

### Horizontal scroll fade

```tsx
<FadeWrapper color="#ffffff" size={16} orientation="horizontal">
  <ScrollView horizontal>
    {/* content */}
  </ScrollView>
</FadeWrapper>
```

### Per-edge control

```tsx
<FadeWrapper color="#000000" sizes={{ top: 0, bottom: 40, left: 16, right: 16 }}>
  <FlatList ... />
</FadeWrapper>
```

### Inward fade

```tsx
<FadeWrapper color="black" inward sizes={{ top: 20, bottom: 30 }}>
  <FlatList ... />
</FadeWrapper>
```

---

## 🛠 Under the Hood

- **iOS:** `CAGradientLayer` sublayers added directly to the target view for zero-overhead compositing
- **Android:** `LinearGradient` shaders drawn on a `ViewGroup` canvas — shaders are cached and only rebuilt on size or color change

---

## 💡 UX Tip

Use `rn-fade-wrapper` to subtly indicate content overflow — especially in carousels, scroll views, and horizontal sliders. Gradients help hint to the user that there's more to scroll, improving engagement.

---

## 📘 License

MIT — free to use, improve and contribute 🎉