blur-react-native

A powerful React Native library that provides native blur effects for both iOS and Android. Create beautiful, performant blur overlays with various blur types and customization options.

⚠️ New Architecture Only: This library requires React Native 0.76+ with the New Architecture (Fabric) enabled.

Features

• 🎨 Multiple Blur Types: Support for 10+ different blur effects on both platforms
• ⚡ Native Performance: Uses UIVisualEffectView on iOS and hardware-accelerated blur on Android
• 🔧 Customizable: Adjustable blur amount and fallback colors
• ♿ Accessibility: Respects reduced transparency settings
• 📱 Cross-Platform: Works on both iOS and Android with platform-specific optimizations
• 🚀 New Architecture: Built exclusively for React Native's New Architecture (Fabric)

Requirements

• React Native 0.76 or higher
• New Architecture (Fabric) enabled
• iOS 13.0 or higher
• Android API 21 (Android 5.0) or higher

Installation

npm install blur-react-native

Or with yarn:

yarn add blur-react-native

iOS Setup

The library will be automatically linked with React Native 0.76+. You just need to install the pods:

cd ios && pod install

Android Setup

The library will be automatically linked with React Native 0.76+. No additional setup is required.

Android Technical Stack

The library automatically chooses the best blur implementation based on the Android API level:

• Android 12+ (API 31+): Uses RenderEffect for hardware-accelerated blur
• Android 5.0+ (API 21+): Uses RenderScript with ScriptIntrinsicBlur for GPU-accelerated blur
• Fallback: Uses optimized software blur with multi-pass box blur algorithm
• Performance Optimizations: Background threading, bitmap caching, and memory management

Usage

Basic Usage

import React from 'react';
import { View, Text } from 'react-native';
import { BlurView } from 'blur-react-native';

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      <BlurView
        blurType="regular"
        style={{
          position: 'absolute',
          top: 100,
          left: 20,
          right: 20,
          height: 200,
          borderRadius: 20,
        }}
      >
        <Text style={{ textAlign: 'center', marginTop: 50 }}>
          Content on blur background
        </Text>
      </BlurView>
    </View>
  );
}

Advanced Usage with Different Blur Types

import React from 'react';
import { BlurView, BlurType } from 'blur-react-native';

const blurTypes: BlurType[] = [
  'light',
  'dark',
  'regular',
  'systemMaterial',
  'systemThickMaterial',
];

export function BlurDemo() {
  return (
    <View>
      {blurTypes.map((type) => (
        <BlurView
          key={type}
          blurType={type}
          blurAmount={80}
          reducedTransparencyFallbackColor="#FFFFFF"
          style={{
            height: 100,
            margin: 10,
            borderRadius: 15,
          }}
        >
          <Text>{type} blur effect</Text>
        </BlurView>
      ))}
    </View>
  );
}

API Reference

Props

Prop	Type	Default	Description
blurType	BlurType	'regular'	The type of blur effect to apply
blurAmount	number	100	Blur intensity from 0-100
reducedTransparencyFallbackColor	string	'#FFFFFF'	Fallback color when reduced transparency is enabled
style	ViewStyle	undefined	Style object for the blur view
children	ReactNode	undefined	Child components to render on top of blur

Blur Types

The following blur types are available on both platforms:

Standard Blur Effects

• 'light' - Light blur effect with white tint
• 'extraLight' - Extra light blur effect with minimal tint
• 'dark' - Dark blur effect with black tint
• 'regular' - Standard blur effect with neutral tint
• 'prominent' - Enhanced blur effect with stronger material appearance

System Material Effects (iOS 13+, Android equivalent)

• 'systemUltraThinMaterial' - Ultra-thin system material
• 'systemThinMaterial' - Thin system material
• 'systemMaterial' - Standard system material
• 'systemThickMaterial' - Thick system material
• 'systemChromeMaterial' - Chrome system material

Examples

Overlay Modal

<BlurView blurType="systemMaterial" style={StyleSheet.absoluteFill}>
  <View style={styles.modalContent}>
    <Text>Modal Content</Text>
  </View>
</BlurView>

Card with Blur Background

<BlurView
  blurType="systemThickMaterial"
  blurAmount={90}
  style={{
    padding: 20,
    borderRadius: 16,
    margin: 16,
  }}
>
  <Text style={styles.cardTitle}>Card Title</Text>
  <Text style={styles.cardContent}>Content here</Text>
</BlurView>

Navigation Bar Blur

<BlurView
  blurType="systemChromeMaterial"
  style={{
    position: 'absolute',
    top: 0,
    left: 0,
    right: 0,
    height: 100,
    paddingTop: 50,
  }}
>
  <Text style={styles.navTitle}>Navigation Title</Text>
</BlurView>

Performance

iOS Performance

• Native UIVisualEffectView: Hardware-accelerated blur with optimal battery usage
• System-level Optimization: Leverages iOS's built-in blur implementation for optimal performance
• Automatic Optimization: Adapts to device capabilities and power state

Android Performance

• Modern Hardware Acceleration: Uses RenderEffect on Android 12+ (API 31+)
• RenderScript GPU Acceleration: Uses ScriptIntrinsicBlur on Android 5.0+ (API 21-30)
• Multi-threaded Processing: Background blur calculation to prevent UI blocking
• Memory Management: Automatic bitmap recycling and memory optimization
• Caching: Intelligent blur result caching for repeated operations
• Fallback Support: Optimized software blur for older/unsupported devices

Accessibility

The library automatically respects the system's "Reduce Transparency" accessibility setting:

• iOS: Automatically detects UIAccessibilityIsReduceTransparencyEnabled()
• Android: Provides fallback color support for accessibility preferences
• Customizable: Use reducedTransparencyFallbackColor to set your preferred fallback

Platform Support

• ✅ iOS 13.0+: Native UIVisualEffectView blur effects
• ✅ Android 5.0+ (API 21+): RenderScript hardware-accelerated blur
• ✅ Android 12+ (API 31+): Modern RenderEffect blur
• ✅ React Native 0.76+: New Architecture (Fabric) support only

Platform-Specific Implementation Details

iOS:

• Uses native UIVisualEffectView for optimal performance and battery life
• All blur types supported with system-native appearance
• Automatic dark/light mode adaptation
• Leverages iOS's built-in hardware acceleration through system APIs

Android:

• API 31+: android.graphics.RenderEffect for hardware-accelerated blur
• API 21-30: RenderScript with ScriptIntrinsicBlur for GPU acceleration
• Fallback: Optimized multi-pass box blur algorithm for older devices
• Background processing with HandlerThread for smooth UI
• LRU bitmap caching for performance optimization
• Automatic memory management and cleanup

Troubleshooting

Common Issues

New Architecture not enabled:

This library requires React Native's New Architecture (Fabric). Ensure you have:

• React Native 0.76 or higher
• New Architecture enabled in your app

Pod install fails:

cd ios && rm -rf Pods Podfile.lock && pod install --repo-update

Build errors:

• Ensure iOS deployment target is 13.0 or higher
• Ensure Android minSdkVersion is 21 or higher
• Ensure compileSdkVersion is 31 or higher for modern blur effects
• Clean build folder: Product → Clean Build Folder in Xcode

Performance issues:

• The library automatically optimizes for device capabilities
• On older devices, reduce blurAmount for better performance

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

Disclaimer: Most of this README and code was written by vibe coding™ 🎵✨ - if you find a bug, please raise a PR! We promise it's more fun than debugging alone 😄

License

MIT

---

Made with create-react-native-library