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