0
# React Native Linear Gradient
1

2
React Native Linear Gradient provides a `<LinearGradient>` component that creates smooth color gradient backgrounds and effects across iOS, Android, and Windows platforms. It offers comprehensive gradient customization through configurable color arrays, start/end positioning, gradient stops, and advanced features like angle-based gradients and animated effects.
3

4
## Package Information
5

6
- **Package Name**: react-native-linear-gradient
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install react-native-linear-gradient`
10

11
## Core Imports
12

13
```javascript
14
import LinearGradient from 'react-native-linear-gradient';
15
```
16

17
For named import:
18

19
```javascript
20
import { LinearGradient } from 'react-native-linear-gradient';
21
```
22

23
## Basic Usage
24

25
```javascript
26
import React from 'react';
27
import { Text, StyleSheet } from 'react-native';
28
import LinearGradient from 'react-native-linear-gradient';
29

30
// Simple vertical gradient
31
<LinearGradient 
32
  colors={['#4c669f', '#3b5998', '#192f6a']} 
33
  style={styles.container}
34
>
35
  <Text style={styles.text}>Hello Gradient</Text>
36
</LinearGradient>
37

38
// Horizontal gradient
39
<LinearGradient
40
  start={{x: 0, y: 0}} 
41
  end={{x: 1, y: 0}}
42
  colors={['#ff0000', '#00ff00', '#0000ff']}
43
  style={styles.container}
44
>
45
  <Text style={styles.text}>Horizontal Gradient</Text>
46
</LinearGradient>
47

48
const styles = StyleSheet.create({
49
  container: {
50
    flex: 1,
51
    justifyContent: 'center',
52
    alignItems: 'center',
53
  },
54
  text: {
55
    color: 'white',
56
    fontSize: 18,
57
  },
58
});
59
```
60

61
## Architecture
62

63
React Native Linear Gradient uses platform-specific implementations to provide optimal performance:
64

65
- **Platform Detection**: Automatically selects the appropriate implementation (iOS, Android, Windows)
66
- **Native Module Integration**: Uses `requireNativeComponent` for platform-specific rendering
67
- **Component Architecture**: React class component with platform-specific rendering optimizations
68
- **Cross-platform API**: Unified interface across all supported platforms
69

70
## Capabilities
71

72
### Linear Gradient Component
73

74
The main component for creating linear gradients with comprehensive customization options.
75

76
```typescript { .api }
77
class LinearGradient extends React.Component<LinearGradientProps> {
78
  static defaultProps: {
79
    start: { x: number; y: number };
80
    end: { x: number; y: number };
81
  };
82
  
83
  /**
84
   * Sets native properties directly on the component
85
   * @param props - Properties to set on the native component
86
   */
87
  setNativeProps(props: LinearGradientProps): void;
88
}
89

90
interface LinearGradientProps extends ViewProps {
91
  /** Array of gradient colors - supports color names, hex, rgb, rgba, and numeric color values */
92
  colors: (string | number)[];
93
  /** Gradient start position as fraction of container size */
94
  start?: {x: number, y: number};
95
  /** Gradient end position as fraction of container size */
96
  end?: {x: number, y: number};
97
  /** Color stop positions mapping to colors array indices */
98
  locations?: number[];
99
  /** Enable angle-based gradient calculation */
100
  useAngle?: boolean;
101
  /** Center point for angle-based gradients */
102
  angleCenter?: {x: number, y: number};
103
  /** Gradient angle in degrees when useAngle is true */
104
  angle?: number;
105
  /** Child elements to render inside the gradient container */
106
  children?: React.ReactNode;
107
}
108
```
109

110
**Usage Examples:**
111

112
```javascript
113
// Basic gradient with color stops
114
<LinearGradient
115
  colors={['#ff0000', '#00ff00', '#0000ff']}
116
  locations={[0, 0.5, 1]}
117
  style={{ height: 200, width: 200 }}
118
/>
119

120
// Angle-based gradient
121
<LinearGradient
122
  colors={['#ff0000', '#0000ff']}
123
  useAngle={true}
124
  angle={45}
125
  angleCenter={{x: 0.5, y: 0.5}}
126
  style={{ height: 200, width: 200 }}
127
/>
128

129
// Diagonal gradient using start/end points
130
<LinearGradient
131
  colors={['#ff0000', '#0000ff']}
132
  start={{x: 0, y: 0}}
133
  end={{x: 1, y: 1}}
134
  style={{ height: 200, width: 200 }}
135
/>
136

137
// Using numeric color values (processed colors)
138
<LinearGradient
139
  colors={[0xff0000ff, 0x00ff00ff, 0x0000ffff]}
140
  style={{ height: 200, width: 200 }}
141
/>
142
```
143

144
### Default Props
145

146
Static default properties applied when props are not specified.
147

148
```typescript { .api }
149
static defaultProps = {
150
  start: { x: 0.5, y: 0.0 },
151
  end: { x: 0.5, y: 1.0 }
152
};
153
```
154

155
### Native Props Method
156

157
Method for setting native properties directly on the component.
158

159
```typescript { .api }
160
/**
161
 * Sets native properties directly on the component
162
 * Useful for performance optimization and direct native interaction
163
 * @param props - Properties to set on the native component
164
 */
165
setNativeProps(props: LinearGradientProps): void;
166
```
167

168
## Types
169

170
```typescript { .api }
171
/** Point coordinates for gradient positioning */
172
interface Point {
173
  x: number,
174
  y: number
175
}
176

177
/** Props interface extending React Native ViewProps */
178
interface LinearGradientProps extends React.ViewProps {
179
  /** Array of colors for the gradient - supports color names, hex, rgb, rgba, and numeric color values */
180
  colors: (string | number)[];
181
  /** Starting point of gradient as fraction (0-1) of container dimensions */
182
  start?: Point;
183
  /** Ending point of gradient as fraction (0-1) of container dimensions */
184
  end?: Point;
185
  /** Array of numbers (0-1) defining color stop positions */
186
  locations?: number[];
187
  /** Whether to use angle-based gradient calculation instead of start/end */
188
  useAngle?: boolean;
189
  /** Center point for angle-based gradients */
190
  angleCenter?: Point;
191
  /** Angle in degrees for gradient direction when useAngle is true */
192
  angle?: number;
193
  /** Child elements to render inside the gradient container (inherited from ViewProps) */
194
  children?: React.ReactNode;
195
}
196
```
197

198
## Advanced Features
199

200
### Transparent Gradients
201

202
For proper transparent effects, use the same color with different alpha values:
203

204
```javascript
205
// Using RGBA for fade effect
206
<LinearGradient 
207
  colors={['rgba(255, 255, 255, 0)', 'rgba(255, 255, 255, 1)']}
208
/>
209

210
// Using hex with alpha
211
<LinearGradient 
212
  colors={['#FFFFFF00', '#FFFFFF']}
213
/>
214
```
215

216
### Animated Gradients
217

218
LinearGradient can be used with React Native's Animated API:
219

220
```javascript
221
import { Animated } from 'react-native';
222

223
const animatedColors = colors.map(color => 
224
  new Animated.Value(/* initial color value */)
225
);
226

227
// Animate color values and use in LinearGradient
228
<LinearGradient colors={animatedColors} />
229
```
230

231
### Text Masking (iOS)
232

233
Use with MaskedViewIOS for gradient text effects:
234

235
```javascript
236
import { MaskedViewIOS } from 'react-native';
237

238
<MaskedViewIOS maskElement={<Text style={styles.text}>Gradient Text</Text>}>
239
  <LinearGradient 
240
    colors={['#ff0000', '#00ff00']} 
241
    start={{x: 0, y: 0}} 
242
    end={{x: 1, y: 0}}
243
  >
244
    <Text style={[styles.text, { opacity: 0 }]}>Gradient Text</Text>
245
  </LinearGradient>
246
</MaskedViewIOS>
247
```
248

249
## Platform-Specific Behavior
250

251
### iOS
252
- Direct native component rendering without wrapper View
253
- Full gradient support with native CAGradientLayer rendering
254
- Supports all gradient features including angle-based gradients
255
- Compatible with MaskedViewIOS for text effects
256
- Maintains start/end point objects as expected by native implementation
257

258
### Android
259
- Enhanced border radius support with per-corner customization
260
- Uses wrapper View structure with absolute positioned gradient overlay for proper child element positioning
261
- Automatic border radius inheritance from container styles with per-corner calculations
262
- Converts start/end point objects to arrays for native Android implementation
263

264
### Windows
265
- Uses wrapper View structure similar to Android but without border radius enhancements
266
- Compatible with React Native Windows platform
267
- Supports core gradient features including start/end points and angle-based gradients
268
- Direct ref assignment for gradient component access
269

270
## Error Handling
271

272
The component includes built-in validation and warnings:
273

274
- **Color/Location Mismatch**: Warns when colors and locations arrays have different lengths
275
- **Deprecated Array Format**: Warns when using deprecated array format for start/end points (should use `{x, y}` objects)
276
- **Auto-correction**: Automatically limits locations array to colors array length to prevent errors