React Native fade gradient wrapper

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.

✨ 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

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 or EAS Build. It does not work in Expo Go.

1. Add the plugin to your app.json:

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

2. Rebuild your native project:

npx expo prebuild
# or use EAS Build
eas build

📱 Platform Support

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

🚀 Quick Start

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)

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

Horizontal scroll fade

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

Per-edge control

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

Inward fade

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