React Native Image Filters

High-performance, GPU-accelerated image editing library for React Native

Transform, filter, and enhance images with blazing-fast GPU processing using Metal (iOS) and GPU-accelerated operations (Android). Built on React Native's New Architecture for optimal performance.

🚀 Features

GPU-Powered Performance

• ⚡ Metal (iOS) & GPU ColorMatrix (Android) for hardware-accelerated processing
• 🎯 Real-time preview with zero lag
• 📱 Optimized for iOS 18+ and Android 13+
• 🏗️ Built with React Native New Architecture (TurboModules)

Image Filtering

• 📸 Document Scanning Filters: scan, enhance, black & white, perspective correction
• 🎨 Photo Editing Filters: 20+ Instagram-style presets (sepia, vintage, vivid, dramatic, etc.)
• 🎛️ Custom Filters: Adjustable brightness, contrast, saturation, and more
• 🔄 Real-time Preview Component: Instant filter visualization
• 💾 Batch Processing: Apply filters to multiple images efficiently

Image Transformation

• ✂️ Interactive Cropping: Touch gestures with grid overlay and aspect ratio locking
• 🔍 Smart Resizing: Multiple modes (cover, contain, stretch) with high-quality scaling
• 🔄 Rotation: Any angle with optional canvas expansion
• 🖼️ Native UI Component: CropperView for interactive cropping

Versatile Input/Output

• 🌐 Support for local (file://) and remote (https://) images
• 📦 Multiple return formats: URI, Base64, or both
• 🗜️ Adjustable JPEG/PNG quality
• 💾 Automatic file management and caching

📸 Screenshots

Filters Tab

Experience real-time GPU-accelerated filtering with instant preview:

| iOS | Android | |-----|---------| | | |

Transform Tab

Interactive cropping, resizing, and rotation with native gesture support:

| iOS | Android | |-----|---------| | | |

📦 Installation

npm install @dariyd/react-native-image-filters

or

yarn add @dariyd/react-native-image-filters

iOS Setup

cd ios && pod install

Requirements:

• iOS 18.0+
• Metal-capable device

Android Setup

Requirements:

• Android 13+ (API 33)
• Gradle auto-configuration included

🎯 Usage

1. Real-Time Filter Preview

Display images with live filter effects:

import { FilteredImageView } from '@dariyd/react-native-image-filters';

function App() {
  const [intensity, setIntensity] = useState(1.0);
  
  return (
    <FilteredImageView
      source={{ uri: 'https://example.com/image.jpg' }}
      filter="vivid"
      intensity={intensity}
      style={{ width: 300, height: 400 }}
      resizeMode="cover"
      onFilterApplied={() => console.log('Filter applied!')}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

2. Apply Filter and Save

Process images and save the filtered result:

import { applyFilter } from '@dariyd/react-native-image-filters';

async function processImage() {
  const result = await applyFilter({
    sourceUri: 'file:///path/to/image.jpg',
    filter: 'scan',
    intensity: 1.0,
    returnFormat: 'uri', // 'uri' | 'base64' | 'both'
    quality: 90,
  });

  console.log('Filtered image:', result.uri);
  console.log('Dimensions:', result.width, 'x', result.height);
}

3. Interactive Image Cropping

Let users crop images with touch gestures:

import { CropperView } from '@dariyd/react-native-image-filters';

function CropScreen() {
  const [cropRect, setCropRect] = useState(null);
  
  return (
    <CropperView
      source={{ uri: 'https://example.com/image.jpg' }}
      aspectRatio={16/9} // Optional: lock aspect ratio
      showGrid={true}
      gridColor="#FFFFFF"
      overlayColor="rgba(0, 0, 0, 0.5)"
      onCropRectChange={(rect) => setCropRect(rect)}
      onGestureEnd={(rect) => console.log('Final crop:', rect)}
      style={{ width: '100%', height: 400 }}
    />
  );
}

4. Crop, Resize, and Rotate

Perform transformations programmatically:

import { cropImage, resizeImage, rotateImage } from '@dariyd/react-native-image-filters';

// Crop to specific region
const cropped = await cropImage({
  sourceUri: 'image.jpg',
  cropRect: { x: 100, y: 100, width: 500, height: 500 },
  returnFormat: 'uri',
  quality: 90,
});

// Resize with different modes
const resized = await resizeImage({
  sourceUri: 'image.jpg',
  width: 800,
  height: 600,
  mode: 'contain', // 'cover' | 'contain' | 'stretch'
  returnFormat: 'uri',
  quality: 90,
});

// Rotate by any angle
const rotated = await rotateImage({
  sourceUri: 'image.jpg',
  degrees: 45,
  expand: true, // Expand canvas to fit rotated image
  returnFormat: 'uri',
  quality: 90,
});

5. Batch Processing

Process multiple images efficiently:

import { applyFilters } from '@dariyd/react-native-image-filters';

async function processMultiple() {
  const results = await applyFilters([
    { sourceUri: 'image1.jpg', filter: 'sepia', intensity: 0.8 },
    { sourceUri: 'image2.jpg', filter: 'vivid', intensity: 1.0 },
    { sourceUri: 'image3.jpg', filter: 'scan', intensity: 1.0 },
  ]);

  results.forEach((result, index) => {
    console.log(`Image ${index}: ${result.uri} (${result.width}x${result.height})`);
  });
}

6. Custom Filters

Create your own filter effects:

const result = await applyFilter({
  sourceUri: 'image.jpg',
  filter: 'custom',
  customParams: {
    brightness: 1.2,    // 0.5 - 2.0
    contrast: 1.5,      // 0.5 - 2.0
    saturation: 0.8,    // 0.0 - 2.0
    hue: 0.1,          // 0.0 - 1.0
    blur: 5,           // 0 - 25
  },
  intensity: 0.9,
});

7. Preload Remote Images

Cache images for faster processing:

import { preloadImage } from '@dariyd/react-native-image-filters';

await preloadImage('https://example.com/large-image.jpg');
// Image is now cached and ready for instant filtering

8. Get Available Filters

Discover all available filters:

import { getAvailableFilters } from '@dariyd/react-native-image-filters';

const documentFilters = await getAvailableFilters('document');
// ['scan', 'blackWhite', 'enhance', 'perspective', 'grayscale', 'colorPop']

const photoFilters = await getAvailableFilters('photo');
// ['sepia', 'noir', 'fade', 'chrome', 'vivid', 'dramatic', 'warm', 'cool', ...]

📚 API Reference

Filtering Functions

applyFilter(options: ApplyFilterOptions): Promise<FilterResult>

Apply a filter to an image and save the result.

Options:

{
  sourceUri: string;           // Image URI (file://, https://, content://)
  filter: FilterName;          // Filter name or 'custom'
  intensity?: number;          // Filter intensity 0-1 (default: 1)
  customParams?: Record<string, number>;  // Custom filter parameters
  returnFormat?: 'uri' | 'base64' | 'both';  // Output format (default: 'uri')
  quality?: number;            // JPEG quality 0-100 (default: 90)
}

Returns:

{
  uri?: string;     // File URI to filtered image
  base64?: string;  // Base64-encoded image data
  width: number;    // Output width in pixels
  height: number;   // Output height in pixels
}

applyFilters(optionsArray: ApplyFilterOptions[]): Promise<FilterResult[]>

Batch process multiple images in parallel.

getAvailableFilters(type?: FilterCategory): Promise<string[]>

Get list of available filters by category.

Parameters:

• type: 'document' | 'photo' | 'custom' (optional, returns all if omitted)

Transformation Functions

cropImage(options: CropImageOptions): Promise<FilterResult>

Crop an image to a specific rectangle.

Options:

{
  sourceUri: string;
  cropRect: {
    x: number;       // Top-left X coordinate
    y: number;       // Top-left Y coordinate
    width: number;   // Crop width
    height: number;  // Crop height
  };
  returnFormat?: 'uri' | 'base64' | 'both';
  quality?: number;  // 0-100
}

resizeImage(options: ResizeImageOptions): Promise<FilterResult>

Resize an image with different scaling modes.

Options:

{
  sourceUri: string;
  width: number;     // Target width
  height: number;    // Target height
  mode: 'cover' | 'contain' | 'stretch';  // Resize mode
  returnFormat?: 'uri' | 'base64' | 'both';
  quality?: number;
}

Resize Modes:

• cover: Scale to fill dimensions, crop excess (maintains aspect ratio)
• contain: Scale to fit within dimensions (maintains aspect ratio, may have padding)
• stretch: Scale to exact dimensions (may distort aspect ratio)

rotateImage(options: RotateImageOptions): Promise<FilterResult>

Rotate an image by any angle.

Options:

{
  sourceUri: string;
  degrees: number;   // Rotation angle (-360 to 360)
  expand?: boolean;  // Expand canvas to fit rotated image (default: true)
  returnFormat?: 'uri' | 'base64' | 'both';
  quality?: number;
}

Utility Functions

preloadImage(uri: string): Promise<void>

Pre-download and cache remote images for faster processing.

clearCache(): Promise<void>

Clear the image cache to free memory.

🖼️ Components

<FilteredImageView>

Real-time filter preview component with GPU acceleration.

Props:

{
  source: { uri: string };     // Image source
  filter: FilterName;          // Filter to apply
  intensity?: number;          // Filter intensity 0-1
  customParams?: Record<string, number>;  // Custom parameters
  resizeMode?: 'cover' | 'contain' | 'stretch' | 'center';
  style?: ViewStyle;
  onFilterApplied?: () => void;
  onError?: (error: Error) => void;
}

<CropperView>

Interactive image cropping component with gesture support.

Props:

{
  source: { uri: string } | string;  // Image source
  initialCropRect?: CropRect;        // Initial crop area
  aspectRatio?: number;              // Lock aspect ratio (e.g., 16/9)
  minCropSize?: { width: number; height: number };  // Min crop dimensions
  showGrid?: boolean;                // Show grid overlay (default: true)
  gridColor?: string;                // Grid line color
  overlayColor?: string;             // Overlay color (default: 'rgba(0,0,0,0.5)')
  style?: ViewStyle;
  onCropRectChange?: (rect: CropRect) => void;  // Real-time updates
  onGestureEnd?: (rect: CropRect) => void;      // Final crop rect
}

Features:

• ✋ Touch gestures: pinch to zoom, pan to move, drag corners/edges to resize
• 📐 Optional aspect ratio locking
• 🎯 Grid overlay for precise alignment
• 🔄 Real-time crop rect updates
• 📱 Native performance on iOS and Android

🎨 Available Filters

Document Scanning Filters

Perfect for scanning documents, receipts, whiteboards, and business cards:

| Filter | Description | Use Case | |--------|-------------|----------| | scan | Adaptive threshold + contrast + sharpness | Default document scan | | blackWhite | High-contrast B&W with noise reduction | Handwritten notes, receipts | | enhance | Smart brightness/contrast/saturation boost | Poor lighting conditions | | perspective | Auto perspective correction | Angled photos | | grayscale | Grayscale conversion | Text documents | | colorPop | Increased saturation and clarity | Colorful documents, diagrams |

Photo Editing Filters

Instagram-style presets with adjustable intensity:

| Filter | Style | Effect | |--------|-------|--------| | sepia | Vintage | Warm brown tone | | noir | Black & White | Classic monochrome | | fade | Retro | Reduced contrast, desaturated | | chrome | Modern | Metallic, high contrast | | transfer | Film | Analog film simulation | | instant | Polaroid | Instant camera look | | vivid | Bold | Boosted colors, sharp | | dramatic | Intense | Deep shadows, vibrant | | warm | Cozy | Orange/yellow tint | | cool | Fresh | Blue tint | | vintage | Old-school | Faded, warm glow | | clarendon | Bright | High contrast, cool shadows | | gingham | Soft | Desaturated, warm highlights | | juno | Colorful | Warm tones, boosted saturation | | lark | Light | Brightened, desaturated | | luna | Moody | Blue/purple shadows | | reyes | Dreamy | Washed out, warm | | valencia | Warm | Orange tint, faded |

Custom Filters

Build your own effects with these parameters:

| Parameter | Range | Default | Description | |-----------|-------|---------|-------------| | brightness | 0.5 - 2.0 | 1.0 | Lightness adjustment | | contrast | 0.5 - 2.0 | 1.0 | Contrast adjustment | | saturation | 0.0 - 2.0 | 1.0 | Color intensity | | hue | 0.0 - 1.0 | 0.0 | Color shift | | blur | 0 - 25 | 0 | Gaussian blur radius | | sharpen | 0.0 - 2.0 | 0.0 | Sharpness | | exposure | -2.0 - 2.0 | 0.0 | Exposure compensation | | temperature | 0.5 - 1.5 | 1.0 | Color temperature | | tint | -1.0 - 1.0 | 0.0 | Green/Magenta shift | | vignette | 0.0 - 1.0 | 0.0 | Edge darkening | | grain | 0.0 - 1.0 | 0.0 | Film grain effect |

⚡ Performance

GPU Acceleration

• iOS: Metal framework for hardware-accelerated image processing

  • Core Image filters with Metal backend
  • Texture caching for real-time preview
  • Zero-copy operations where possible

• Android: GPU-accelerated ColorMatrix operations

  • Hardware-accelerated bitmap processing
  • Glide image loading with disk/memory caching
  • Optimized for minimal memory footprint

Optimization Features

• ✅ Async processing on background threads
• ✅ In-memory caching for frequently used images
• ✅ Progressive image loading for remote URLs
• ✅ Automatic memory management
• ✅ Lazy initialization of GPU resources
• ✅ Batch processing for multiple images

Benchmarks

Processing a 4000x3000px image on iPhone 15 Pro / Pixel 8 Pro:

| Operation | iOS (Metal) | Android (GPU) | |-----------|-------------|---------------| | Apply filter | ~50ms | ~80ms | | Real-time preview | 60 FPS | 60 FPS | | Crop + Resize | ~30ms | ~40ms | | Rotate 90° | ~20ms | ~25ms | | Batch (5 images) | ~250ms | ~400ms |

Actual performance may vary based on device and image size.

📋 Requirements

• React Native: 0.74+ (New Architecture required)
• iOS: 18.0+ with Metal-capable device
• Android: API 33+ (Android 13+)
• Node.js: 20+

React Native New Architecture

This library is built exclusively for the New Architecture. Make sure your app has the New Architecture enabled:

iOS: Set in Podfile:

use_frameworks! :linkage => :static
$RNNewArchEnabled = true

Android: Set in gradle.properties:

newArchEnabled=true

🐛 Troubleshooting

iOS Issues

Build error: "Cannot find Metal shader"

• Clean build folder: Product > Clean Build Folder in Xcode
• Delete Pods folder and run pod install

Runtime error: "Metal device not available"

• This library requires a Metal-capable device (iPhone 6s or later)
• Simulator support depends on your Mac's GPU

Android Issues

Build error: "Failed to resolve: react-native-image-filters"

• Run ./gradlew clean in android/ folder
• Check that New Architecture is enabled in gradle.properties

Runtime error: "Canvas: trying to use a recycled bitmap"

• This is fixed in version 1.0.0+
• Make sure you're using the latest version

💡 Example App

A complete example app is included in the example/ directory demonstrating:

• ✅ Real-time filter preview with intensity control
• ✅ All document and photo filters
• ✅ Interactive image cropping
• ✅ Resize and rotate operations
• ✅ Batch processing
• ✅ Custom filter parameters
• ✅ Show original image toggle

Run the example:

# Install dependencies
cd example
npm install

# iOS
cd ios && pod install && cd ..
npm run ios

# Android
npm run android

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Metal framework (Apple) for iOS GPU acceleration
• Android GPU ColorMatrix for Android acceleration
• React Native New Architecture team
• Glide library for Android image loading

📞 Support

• 🐛 Report a Bug
• 💬 Ask a Question
• 📖 Read the API Docs
• 📝 View Changelog

💖 Support the Project

If you find this library helpful, consider supporting its development:

☕ Buy Me a Coffee

💸 Send via Revolut

Scan the QR code or use the link below:

Send on Revolut →

Made with ❤️ for the React Native community