tessl/npm-react-native-linear-gradient

A LinearGradient component for React Native that enables developers to create smooth color gradient backgrounds and effects across iOS, Android, and Windows platforms.

—

Pending

Overview

Eval results

Files

React Native Linear Gradient

Name: tessl/npm-react-native-linear-gradient
Author: tessl

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.

Package Information

Package Name: react-native-linear-gradient
Package Type: npm
Language: JavaScript (with TypeScript definitions)
Installation: npm install react-native-linear-gradient

Core Imports

import LinearGradient from 'react-native-linear-gradient';

For named import:

import { LinearGradient } from 'react-native-linear-gradient';

Basic Usage

import React from 'react';
import { Text, StyleSheet } from 'react-native';
import LinearGradient from 'react-native-linear-gradient';

// Simple vertical gradient
<LinearGradient 
  colors={['#4c669f', '#3b5998', '#192f6a']} 
  style={styles.container}
>
  <Text style={styles.text}>Hello Gradient</Text>
</LinearGradient>

// Horizontal gradient
<LinearGradient
  start={{x: 0, y: 0}} 
  end={{x: 1, y: 0}}
  colors={['#ff0000', '#00ff00', '#0000ff']}
  style={styles.container}
>
  <Text style={styles.text}>Horizontal Gradient</Text>
</LinearGradient>

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  text: {
    color: 'white',
    fontSize: 18,
  },
});

Architecture

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

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

Capabilities

Linear Gradient Component

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

class LinearGradient extends React.Component<LinearGradientProps> {
  static defaultProps: {
    start: { x: number; y: number };
    end: { x: number; y: number };
  };
  
  /**
   * Sets native properties directly on the component
   * @param props - Properties to set on the native component
   */
  setNativeProps(props: LinearGradientProps): void;
}

interface LinearGradientProps extends ViewProps {
  /** Array of gradient colors - supports color names, hex, rgb, rgba, and numeric color values */
  colors: (string | number)[];
  /** Gradient start position as fraction of container size */
  start?: {x: number, y: number};
  /** Gradient end position as fraction of container size */
  end?: {x: number, y: number};
  /** Color stop positions mapping to colors array indices */
  locations?: number[];
  /** Enable angle-based gradient calculation */
  useAngle?: boolean;
  /** Center point for angle-based gradients */
  angleCenter?: {x: number, y: number};
  /** Gradient angle in degrees when useAngle is true */
  angle?: number;
  /** Child elements to render inside the gradient container */
  children?: React.ReactNode;
}

Usage Examples:

// Basic gradient with color stops
<LinearGradient
  colors={['#ff0000', '#00ff00', '#0000ff']}
  locations={[0, 0.5, 1]}
  style={{ height: 200, width: 200 }}
/>

// Angle-based gradient
<LinearGradient
  colors={['#ff0000', '#0000ff']}
  useAngle={true}
  angle={45}
  angleCenter={{x: 0.5, y: 0.5}}
  style={{ height: 200, width: 200 }}
/>

// Diagonal gradient using start/end points
<LinearGradient
  colors={['#ff0000', '#0000ff']}
  start={{x: 0, y: 0}}
  end={{x: 1, y: 1}}
  style={{ height: 200, width: 200 }}
/>

// Using numeric color values (processed colors)
<LinearGradient
  colors={[0xff0000ff, 0x00ff00ff, 0x0000ffff]}
  style={{ height: 200, width: 200 }}
/>

Default Props

Static default properties applied when props are not specified.

static defaultProps = {
  start: { x: 0.5, y: 0.0 },
  end: { x: 0.5, y: 1.0 }
};

Native Props Method

Method for setting native properties directly on the component.

/**
 * Sets native properties directly on the component
 * Useful for performance optimization and direct native interaction
 * @param props - Properties to set on the native component
 */
setNativeProps(props: LinearGradientProps): void;

Types

/** Point coordinates for gradient positioning */
interface Point {
  x: number,
  y: number
}

/** Props interface extending React Native ViewProps */
interface LinearGradientProps extends React.ViewProps {
  /** Array of colors for the gradient - supports color names, hex, rgb, rgba, and numeric color values */
  colors: (string | number)[];
  /** Starting point of gradient as fraction (0-1) of container dimensions */
  start?: Point;
  /** Ending point of gradient as fraction (0-1) of container dimensions */
  end?: Point;
  /** Array of numbers (0-1) defining color stop positions */
  locations?: number[];
  /** Whether to use angle-based gradient calculation instead of start/end */
  useAngle?: boolean;
  /** Center point for angle-based gradients */
  angleCenter?: Point;
  /** Angle in degrees for gradient direction when useAngle is true */
  angle?: number;
  /** Child elements to render inside the gradient container (inherited from ViewProps) */
  children?: React.ReactNode;
}

Advanced Features

Transparent Gradients

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

// Using RGBA for fade effect
<LinearGradient 
  colors={['rgba(255, 255, 255, 0)', 'rgba(255, 255, 255, 1)']}
/>

// Using hex with alpha
<LinearGradient 
  colors={['#FFFFFF00', '#FFFFFF']}
/>

Animated Gradients

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

import { Animated } from 'react-native';

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

// Animate color values and use in LinearGradient
<LinearGradient colors={animatedColors} />

Text Masking (iOS)

Use with MaskedViewIOS for gradient text effects:

import { MaskedViewIOS } from 'react-native';

<MaskedViewIOS maskElement={<Text style={styles.text}>Gradient Text</Text>}>
  <LinearGradient 
    colors={['#ff0000', '#00ff00']} 
    start={{x: 0, y: 0}} 
    end={{x: 1, y: 0}}
  >
    <Text style={[styles.text, { opacity: 0 }]}>Gradient Text</Text>
  </LinearGradient>
</MaskedViewIOS>

Platform-Specific Behavior

iOS

Direct native component rendering without wrapper View
Full gradient support with native CAGradientLayer rendering
Supports all gradient features including angle-based gradients
Compatible with MaskedViewIOS for text effects
Maintains start/end point objects as expected by native implementation

Android

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

Windows

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

Error Handling

The component includes built-in validation and warnings:

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

Install with Tessl CLI

npx tessl i tessl/npm-react-native-linear-gradient

docs

index.md

tile.json