react-native-gradient-wrapper

GradientWrapper for React Native

GradientWrapper is a flexible, animated wrapper component for React Native that adds background and border gradients with support for animations, angle directions, theming, and per-side customization. It’s designed to be beginner-friendly while still powerful enough for advanced use cases.

• ✅ Custom background gradients
• ✅ Animated gradient transitions (color morphing)
• ✅ Rotating background or border gradients
• ✅ Light/Dark/Auto theme-aware defaults
• ✅ Angle-based direction control for gradients
• ✅ Per-side border gradient customization
• ✅ Touchable feedback (scale on press)
• ✅ Optional gradient animation stop timers (stopBackgroundAfter, stopBorderAfter)

Installation

Install peer dependencies first:

npm install react-native-gradient-wrapper react-native-linear-gradient

If you're using Expo, install the linear gradient library with:

npx expo install react-native-gradient-wrapper expo-linear-gradient

Expo will automatically handle linking and compatibility.

Border Gradient Usage

import { GradientWrapper } from 'react-native-gradient-wrapper';

<GradientWrapper
  borderGradient={['rgba(0, 0, 255, 0.9)', 'rgba(186, 0, 146, 0.97)']} 
  borderRadius={30}
  stopBorderAfter={300000} // stop after 30 sec
  borderAngle={46.38} // instead of start and end X,Y you can use angle
  borderWidth={2}
  contentStyle={{
    height: 35,
    width: '100%',
    alignItems: 'center',
    alignContent: 'center',
    flex: 1,
    padding: 10,
  }}
  style={{ margin: 0 }}
  enableFeedback
  backgroundGradient={['rgb(155, 70, 0)', 'rgb(50, 0, 56)']}
  backgroundLocations={[0, 0.6, 1]}
  angle={90} // angle for background color
>
  <TouchableOpacity onPress={() => setSpeed(prev => Math.max(1000, prev - 500))}>
    <Text style={{ color: '#FFFFFF' }}>Animated Border Button</Text>
  </TouchableOpacity>
</GradientWrapper>

Background Color Usage

import { GradientWrapper } from 'react-native-gradient-wrapper';

    <GradientWrapper
      backgroundGradient={['#5A3F37', '#2C7744', '#5A3F37']}
      backgroundRotationSpeed={4000}
      animated={true} //color rotation
      style={styles.container}
      borderWidth={0}
      angle={46.36}
    //   backgroundLocations={[0,0.5, 1]}//for background location
      borderRadius={0}
    >
      <View style={styles.content}>
        <Text style={styles.title}>Animated Background Gradient</Text>
      </View>
    </GradientWrapper>

Props Reference

Prop	Type	Description
backgroundGradient	string[]	Background color array
borderGradient	string[]	Border color array (fallback if no sides defined)
borderTopGradient	string[]	Top border only
borderBottomGradient	string[]	Bottom border only
borderLeftGradient	string[]	Left border only
borderRightGradient	string[]	Right border only
borderWidth	number	Width of the border (default 2)
borderRadius	number	Corner radius (default 10)
backgroundRotation	'clockwise' | 'anticlockwise' | 'none'	Rotating background effect
borderRotation	'clockwise' | 'anticlockwise' | 'none'	Rotating border effect
backgroundRotationSpeed	number	Milliseconds for one background rotation cycle
borderRotationSpeed	number	Milliseconds for one border rotation cycle
stopBackgroundAfter	number	Stops background animation after X ms
stopBorderAfter	number	Stops border animation after X ms
animated	boolean	Animate colors across gradient stops
angle	number	Direction in degrees (e.g. 45) for background
borderAngle	number	Direction in degrees for border gradient
theme	'light' | 'dark' | 'auto'	Theme-based fallback gradient colors
onPress, onLongPress	() => void	Press handlers
enableFeedback	boolean	Scale animation on press (default true)

Comparison with Other Libraries

Feature / Library	react-native-gradient-wrapper	react-native-linear-gradient	react-native-gradients	react-native-animated-linear-gradient
✅ Background gradient support	✅	✅	✅	✅
✅ Border gradient	✅	❌	❌	❌
✅ Animated color transition (morph)	✅	❌	❌	✅ (only background)
✅ Rotation animation support	✅	❌	❌	❌
✅ Per-side border control	✅	❌	❌	❌
✅ Theme-aware fallback colors	✅	❌	❌	❌
✅ Pressable feedback (scale)	✅	❌	❌	❌
✅ Angle-based gradient direction	✅	✅	✅	✅
✅ Stop animations after delay	✅	❌	❌	❌

Note: GradientWrapper internally uses react-native-linear-gradient and extends it with a complete system of wrappers, animations, fallback themes, and UI feedback.

Ideal Use Cases

• Buttons with animated borders
• Cards with glowing outlines
• Containers with gradient backgrounds
• Interactive boxes with animated themes
• Light/Dark mode responsive UI blocks

Future Plans

• Support for Lottie-like morphing gradients
• Web support (React Native Web)
• Built-in presets (e.g. fire, neon, galaxy)

Props

Check src/index.tsx for all available props and defaults.

License

MIT