@sbaiahmed1/react-native-blur

A modern React Native library providing three specialized components for advanced visual effects: BlurView for native blur effects, LiquidGlassView for cutting-edge liquid glass effects on iOS 26+ (with Android fallback to enhanced blur) and ProgressiveBlurView for smooth, variable blur transitions.`

📦 Current Version: 4.0.0 | ⚠️ Breaking Changes: If upgrading from 3.x, see Breaking Changes section.

Demo

iOS (left) and Android (right) blur effects in action
Liquid Glass effect in action (iOS 26+ only)
⚠️ Android automatically falls back to enhanced blur with tint overlay

Requirements

Platform	Minimum Version
iOS	iOS 13.0+
Xcode	Xcode 26.0+ (for liquid glass support)
React Native	0.68+ (New Architecture)
Android	API 24+ (Android 7.0)
Android Gradle Plugin	8.9.1+

⚠️ Note: LiquidGlassView requires Xcode 26.0+ and iOS 26+ for full glass effects. The component automatically falls back to enhanced blur on older versions.

⚠️ Breaking Changes in v4.0.0

Important: Version 4.0.0 introduces significant API changes. If you're upgrading from 3.x, please read this section carefully.

What Changed

In version 3.x, we had a single BlurView component with a type prop that switched between blur and liquid glass modes:

// ❌ Old API (v3.x) - DEPRECATED
<BlurView
  type="blur" // or "liquidGlass"
  blurType="light"
  blurAmount={10}
  glassType="regular" // Mixed blur and glass props
  glassTintColor="#007AFF"
/>

In version 4.0.0, we've separated concerns into two dedicated components for better architecture and cleaner APIs:

// ✅ New API (v4.0.0) - Current
import { BlurView, LiquidGlassView } from '@sbaiahmed1/react-native-blur';

// For blur effects
<BlurView
  blurType="light"
  blurAmount={10}
/>

// For liquid glass effects (iOS 26+)
<LiquidGlassView
  glassType="regular"
  glassTintColor="#007AFF"
  glassOpacity={0.8}
/>

Migration from 3.x to 4.0.0

If you were using blur mode:

// Before (3.x)
<BlurView type="blur" blurType="light" blurAmount={10} />

// After (4.0.0)
<BlurView blurType="light" blurAmount={10} />

If you were using liquid glass mode:

// Before (3.x)
<BlurView
  type="liquidGlass"
  glassType="regular"
  glassTintColor="#007AFF"
  glassOpacity={0.8}
/>;

// After (4.0.0)
import { LiquidGlassView } from '@sbaiahmed1/react-native-blur';

<LiquidGlassView
  glassType="regular"
  glassTintColor="#007AFF"
  glassOpacity={0.8}
/>;

Why This Change?

🎯 Cleaner APIs: Each component now has focused props relevant to its purpose
📦 Better Tree-Shaking: Import only what you need
🔧 Type Safety: Separate TypeScript definitions prevent mixing incompatible props
🏗️ Better Architecture: Separation of concerns following React best practices
📖 Clearer Code: More explicit about which effect you're using

Summary

v3.x: Single BlurView component with type prop (blur or liquidGlass)
v4.0.0: Two components - BlurView for blur, LiquidGlassView for glass effects
Action Required: Update imports and split your components based on the effect type you need

Features

� Three Specialized Components:
- BlurView - Dedicated blur effects component with multiple blur types
- ProgressiveBlurView - Variable/gradient blur transitions (iOS & Android)
- LiquidGlassView - Separate component for iOS 26+ liquid glass effects
�🌊 Liquid Glass Effects: Revolutionary glass effects using iOS 26+ UIGlassEffect API
🎨 Multiple Blur Types: Support for various blur styles including system materials on iOS
📱 Cross-Platform: Works on both iOS and Android
♿ Accessibility: Automatic fallback for reduced transparency settings
🔧 TypeScript: Full TypeScript support with proper type definitions for both components
🚀 Turbo Module: Built with React Native's new architecture (Fabric)
🎯 Customizable: Adjustable blur intensity, glass tint colors, and opacity
💡 Performance Optimized: Uses hardware acceleration for smooth rendering
🛠️ Easy to Use: Simple, focused APIs for each effect type
📦 Modern: Uses SwiftUI for iOS and Kotlin for Android, ensuring cutting-edge development practices
🔄 Smart Fallbacks: Graceful degradation from liquid glass to blur on older iOS versions

Comparison with Other Libraries

Key Advantages

Two Specialized Components: Separate BlurView and LiquidGlassView components for clean architecture
Liquid Glass Effects: Only library with iOS 26+ UIGlassEffect support
Real Android Blur: Hardware-accelerated blur on Android (not overlay)
New Architecture: Built for Fabric/Turbo Modules
Modern Stack: SwiftUI for iOS, Kotlin for Android
Full TypeScript: Complete type definitions for both components

vs. @react-native-community/blur

✅ Dedicated components vs single component with mode switching
✅ Liquid glass effects (iOS 26+)
✅ Better new architecture support
✅ Separate prop types for each component

vs. expo-blur

✅ No Expo dependency required
✅ Real Android blur (not experimental)
✅ Works with bare React Native projects
✅ Liquid glass effects support

Migration Guide

From @react-native-community/blur

// Before
import { BlurView } from '@react-native-community/blur';

// After - same API, now with dedicated components
import { BlurView, LiquidGlassView } from '@sbaiahmed1/react-native-blur';

// Use BlurView for standard blur
<BlurView blurType="light" blurAmount={10} />

// Or LiquidGlassView for glass effects (iOS 26+)
<LiquidGlassView glassType="regular" glassTintColor="#007AFF" glassOpacity={0.8} />

From expo-blur

// Before
import { BlurView } from 'expo-blur';
<BlurView intensity={50} tint="light" />;

// After
import { BlurView } from '@sbaiahmed1/react-native-blur';
<BlurView blurAmount={50} blurType="light" />;

Migration Steps:

Uninstall old library: npm uninstall @react-native-community/blur expo-blur
Install: npm install @sbaiahmed1/react-native-blur
Update imports
Run cd ios && pod install

Installation

⚠️ ANDROID USERS: This library requires Android Gradle Plugin (AGP) version 8.9.1 or newer. See Android Setup Requirements for details.

npm install @sbaiahmed1/react-native-blur
# or
yarn add @sbaiahmed1/react-native-blur

iOS Setup

Run pod install:

cd ios && pod install

Android Setup

The library uses native Android blur with automatic platform detection. No additional configuration required beyond ensuring minimum requirements:

Min SDK: API 24 (Android 7.0)
Android Gradle Plugin: 8.9.1+

⚠️ AGP Requirement: Requires Android Gradle Plugin 8.9.1 or newer. Check android/build.gradle:
classpath "com.android.tools.build:gradle:8.9.1" // or higher

📦 Dependency: The library uses QmBlurView from Maven Central:
implementation 'com.qmdeve:QmBlurView:1.0.4.3'

The implementation automatically handles different Android versions:

Android 12+: Uses RenderEffectBlur
Android 10-11: Falls back to RenderScriptBlur
Older versions: Lightweight overlay fallback

Usage

The library now provides three specialized components for different visual effects:

BlurView - Standard Blur Effects

Use BlurView for standard blur effects across all platforms:

Basic Usage

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

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

Advanced Blur Usage

import React from 'react';
import { BlurView } from '@sbaiahmed1/react-native-blur';

function MyComponent() {
  return (
    <BlurView
      blurType="systemMaterial"
      blurAmount={50}
      reducedTransparencyFallbackColor="#FFFFFF80"
      style={{
        padding: 20,
        borderRadius: 15,
      }}
    >
      <Text>Advanced blur with custom fallback</Text>
    </BlurView>
  );
}

ProgressiveBlurView - Variable/Gradient Blur

NOTE: Progressive blur offset works different between android and iOS

Use ProgressiveBlurView for smooth, gradient blur transitions. This component works on both iOS and Android.

import React from 'react';
import { ProgressiveBlurView } from '@sbaiahmed1/react-native-blur';

function GradientBlurComponent() {
  return (
    <ProgressiveBlurView
      blurType="light"
      blurAmount={30}
      direction="blurredTopClearBottom"
      startOffset={0}
      style={{ height: 200 }}
    >
      <Text>Progressive blur from top (blurred) to bottom (clear)</Text>
    </ProgressiveBlurView>
  );
}

Locked Content Example

Perfect for paywall/premium content:

<View style={{ position: 'relative' }}>
  <Text>Long content here...</Text>

  {/* Progressive blur overlay */}
  <ProgressiveBlurView
    blurType="light"
    blurAmount={20}
    direction="blurredBottomClearTop"
    startOffset={0.2}
    style={{
      position: 'absolute',
      bottom: 0,
      left: 0,
      right: 0,
      height: 200,
    }}
  >
    <Text>🔒 Unlock to Read More</Text>
    <Button title="Purchase" />
  </ProgressiveBlurView>
</View>

LiquidGlassView - Liquid Glass Effects (iOS 26+)

Use LiquidGlassView for cutting-edge liquid glass effects. Note: This component automatically falls back to enhanced blur on Android and older iOS versions.

import React from 'react';
import { LiquidGlassView } from '@sbaiahmed1/react-native-blur';

function LiquidGlassComponent() {
  return (
    <LiquidGlassView
      glassType="regular"
      glassTintColor="#007AFF"
      glassOpacity={0.8}
      style={{
        padding: 20,
        borderRadius: 20,
      }}
    >
      <Text>Beautiful liquid glass effect</Text>
    </LiquidGlassView>
  );
}

Interactive Liquid Glass

import React from 'react';
import { LiquidGlassView } from '@sbaiahmed1/react-native-blur';

function InteractiveGlass() {
  return (
    <LiquidGlassView
      glassType="regular"
      glassTintColor="#007AFF"
      glassOpacity={0.9}
      isInteractive={true} // Enables touch interaction (iOS 26+ only)
      ignoreSafeArea={false}
      style={{
        flex: 1,
        padding: 30,
      }}
    >
      <Text>Interactive liquid glass that responds to touch</Text>
    </LiquidGlassView>
  );
}

Props

The library now provides two separate components with their own props:

BlurView Props

All props are optional and have sensible defaults.

Prop	Type	Default	Description
`blurType`	`BlurType`	`'xlight'`	The type of blur effect to apply
`blurAmount`	`number`	`10.0`	The intensity of the blur effect (0-100)
`ignoreSafeArea`	`boolean`	`false`	(iOS only) Controls whether the blur effect should ignore all safe area edges
`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 inside the blur view

ProgressiveBlurView Props

All props are optional and have sensible defaults.

Prop	Type	Default	Description
`blurType`	`BlurType`	`'regular'`	The type of blur effect to apply
`blurAmount`	`number`	`20.0`	Maximum blur radius in pixels
`direction`	`'blurredTopClearBottom' \| 'blurredBottomClearTop'`	`'blurredTopClearBottom'`	Direction of the blur gradient
`startOffset`	`number`	`0.0`	Where the gradient starts (0.0 to 1.0)
`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 inside the blur view

Platform Note: ProgressiveBlurView works on both iOS and Android.

iOS: Uses private Core Animation filters for variable blur effects

Android: Extends QMBlur's BlurView with custom gradient masking to create progressive blur effect

LiquidGlassView Props

All props are optional and have sensible defaults.

Prop	Type	Default	Description
`glassType`	`GlassType`	`'clear'`	The type of glass effect (iOS 26+ only)
`glassTintColor`	`string`	`'clear'`	The tint color for glass effect. Accepts hex colors or color names
`glassOpacity`	`number`	`1.0`	The opacity of glass effect (0-1)
`isInteractive`	`boolean`	`true`	(iOS 26+ only) Controls whether the liquid glass effect is interactive and reacts to touch
`ignoreSafeArea`	`boolean`	`false`	(iOS only) Controls whether the glass effect should ignore all safe area edges
`reducedTransparencyFallbackColor`	`string`	`'#FFFFFF'`	Fallback color when reduced transparency is enabled or on older iOS versions
`style`	`ViewStyle`	`undefined`	Style object for the glass view
`children`	`ReactNode`	`undefined`	Child components to render inside the glass view

Note: The BlurType and GlassType are exported types from the library. See Blur Types and Glass Types sections below for all available values.

Platform Note: LiquidGlassView automatically falls back to BlurView on Android and iOS versions older than iOS 26.

Blur Types (BlurView)

The following blur types are supported for BlurView:

'light' - Light blur effect
'dark' - Dark blur effect
'xlight' - Extra light blur effect
'extraDark' - Extra dark blur effect
'regular' - Regular blur (iOS 10+)
'prominent' - Prominent blur (iOS 10+)
'systemUltraThinMaterial' - Ultra thin material (iOS 13+)
'systemThinMaterial' - Thin material (iOS 13+)
'systemMaterial' - Material (iOS 13+)
'systemThickMaterial' - Thick material (iOS 13+)
'systemChromeMaterial' - Chrome material (iOS 13+)
'systemUltraThinMaterialLight' - Ultra thin light material (iOS 13+)
'systemThinMaterialLight' - Thin light material (iOS 13+)
'systemMaterialLight' - Light material (iOS 13+)
'systemThickMaterialLight' - Thick light material (iOS 13+)
'systemChromeMaterialLight' - Chrome light material (iOS 13+)
'systemUltraThinMaterialDark' - Ultra thin dark material (iOS 13+)
'systemThinMaterialDark' - Thin dark material (iOS 13+)
'systemMaterialDark' - Dark material (iOS 13+)
'systemThickMaterialDark' - Thick dark material (iOS 13+)
'systemChromeMaterialDark' - Chrome dark material (iOS 13+)

Glass Types (LiquidGlassView)

The following glass types are supported for LiquidGlassView on iOS 26+:

'clear' - Clear glass effect (default)
'regular' - Regular glass effect with more pronounced appearance

Note: On Android and iOS versions older than iOS 26, LiquidGlassView automatically falls back to an enhanced blur effect that approximates the glass appearance.

Platform Differences

iOS

Both components have been completely rewritten using SwiftUI for modern performance and features:

BlurView

iOS 13+: Uses native UIVisualEffectView with precise blur intensity control
Older iOS: Graceful fallback to standard blur effects
SwiftUI Integration: Leverages SwiftUI's declarative UI for better performance and maintainability

LiquidGlassView

iOS 26+: Uses native UIGlassEffect API for true liquid glass effects with customizable tint colors and opacity
iOS < 26: Automatically falls back to BlurView with enhanced blur effects
SwiftUI Implementation: Full hardware-accelerated glass effects with interactive touch support

Android

BlurView

The component uses the QmBlurView library to provide real blur effects with hardware acceleration. The implementation supports multiple blur algorithms and gracefully falls back to translucent overlay approximation on devices with limited graphics capabilities.

LiquidGlassView

⚠️ Platform Limitation: Liquid glass effects are iOS 26+ exclusive. On Android, LiquidGlassView automatically falls back to BlurView with enhanced blur and tint overlay to approximate the visual effect.

Accessibility

Both components automatically respect the "Reduce Transparency" accessibility setting:

BlurView

iOS: When reduce transparency is enabled, the blur view is hidden and a fallback view with solid color is shown
Android: The fallback color is always used as the base for the blur approximation

LiquidGlassView

iOS 26+: When reduce transparency is enabled, the liquid glass effect is hidden and a fallback view with solid color is shown
iOS < 26 & Android: Automatically falls back to BlurView behavior

You can customize the fallback color using the reducedTransparencyFallbackColor prop on both components.

TypeScript Support

This package includes full TypeScript definitions for both components:

import {
  BlurView,
  LiquidGlassView,
  BlurType,
  GlassType,
  BlurViewProps,
  LiquidGlassViewProps,
} from '@sbaiahmed1/react-native-blur';

// BlurType is exported for type checking
const blurType: BlurType = 'systemMaterial';

// GlassType for liquid glass effects
const glassType: GlassType = 'regular';

// BlurViewProps for component props
interface MyBlurComponentProps {
  blurProps: BlurViewProps;
}

// LiquidGlassViewProps for glass component props
interface MyGlassComponentProps {
  glassProps: LiquidGlassViewProps;
}

// Example with BlurView properties
const blurProps: BlurViewProps = {
  blurType: 'systemMaterial',
  blurAmount: 50,
  reducedTransparencyFallbackColor: '#FFFFFF',
};

// Example with LiquidGlassView properties
const liquidGlassProps: LiquidGlassViewProps = {
  glassType: 'regular',
  glassTintColor: '#007AFF',
  glassOpacity: 0.8,
  isInteractive: true,
};

Example App

The package includes a comprehensive example app that demonstrates both components with all their features. The example app features:

BlurView Demo: Interactive blur type selector with live preview of all blur types
LiquidGlassView Demo: Showcase of iOS 26+ glass effects with customizable properties
Practical Use Cases: Real-world examples like cards, modals, and overlays using both components
Comparison Views: Side-by-side comparisons between BlurView and LiquidGlassView effects
Platform Fallbacks: Visual demonstrations of how effects degrade gracefully on older platforms

To run the example:

cd example
yarn install
# For iOS
yarn ios
# For Android
yarn android

Performance Considerations

BlurView

iOS:
- SwiftUI Implementation: Enhanced performance with declarative UI updates
- Native Blur Effects: Hardware-accelerated UIVisualEffectView for performant rendering
- Precise Control: Adjustable blur intensity with smooth animations
Android:
- Real blur effects are hardware-accelerated with QmBlurView
- Fallback to lightweight overlay when needed on limited devices

LiquidGlassView

iOS 26+:
- Hardware-Accelerated Glass: Native UIGlassEffect API with minimal performance impact
- Interactive Effects: Smooth touch interactions without performance degradation
- SwiftUI Powered: Optimized declarative UI updates
iOS < 26 & Android:
- Automatic fallback to BlurView with enhanced blur effects
- Same performance characteristics as BlurView

General Tips

Avoid using too many blur/glass views simultaneously on lower-end devices
Consider using reducedTransparencyFallbackColor for better accessibility
LiquidGlassView automatically falls back to BlurView on unsupported platforms
Both components are optimized for React Native's new architecture (Fabric)

What's New in v4.0.0

⚠️ Breaking Changes: v4.0.0 introduces a major API redesign. See Breaking Changes section above for migration guide.

🎯 Component Separation (BREAKING CHANGE)

Two Specialized Components: Split single BlurView into dedicated BlurView and LiquidGlassView components
Removed type prop: No more switching between blur/liquidGlass modes - use the appropriate component instead
Cleaner APIs: Each component has focused props without mixing blur and glass properties
Better Architecture: True separation of concerns following React best practices
Improved Type Safety: Separate TypeScript definitions prevent incompatible prop combinations

🌊 Liquid Glass Effects (iOS 26+)

Revolutionary glass effects using Apple's new UIGlassEffect API
Dedicated LiquidGlassView component for glass-specific effects
Customizable glass types: clear and regular
Adjustable tint colors and opacity for stunning visual effects
Automatic fallback to enhanced blur on older iOS versions and Android

🔄 SwiftUI Rewrite

Complete iOS implementation rewritten using SwiftUI
Enhanced performance with declarative UI updates
Better integration with React Native's new architecture
Improved blur intensity control with precise animation handling

📱 Enhanced Example App

Separate demonstrations for BlurView and LiquidGlassView
Interactive property controls for real-time customization
Practical use case examples (cards, modals, overlays)
Comparison views showing both components side by side

🛠️ Developer Experience

Full TypeScript support with separate prop types for each component (BlurViewProps, LiquidGlassViewProps)
Cleaner, more intuitive API design
Improved component layout handling
Better accessibility support with smart fallbacks
Enhanced documentation with breaking changes guide

Contributing

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

License

MIT

📊 Stats

Credits

Progressive Blur Implementation:

VariableBlur by @nikstar: https://github.com/nikstar/VariableBlur
Original concept by @jtrivedi: https://github.com/jtrivedi/VariableBlurView

Android Blur:

QMBlur library: https://github.com/QmDeve/QmBlurView

Built with create-react-native-library

Name		Name	Last commit message	Last commit date
Latest commit History 119 Commits
.github		.github
.yarn		.yarn
android		android
example		example
ios		ios
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
.watchmanconfig		.watchmanconfig
.yarnrc.yml		.yarnrc.yml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ReactNativeBlur.podspec		ReactNativeBlur.podspec
android-blur-glass-demo.gif		android-blur-glass-demo.gif
android-demo.gif		android-demo.gif
babel.config.js		babel.config.js
eslint.config.mjs		eslint.config.mjs
iOS-demo.gif		iOS-demo.gif
ios-blur-glass-demo.gif		ios-blur-glass-demo.gif
lefthook.yml		lefthook.yml
liquidGlass.gif		liquidGlass.gif
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
yarn.lock		yarn.lock

License

sbaiahmed1/react-native-blur

Folders and files

Latest commit

History

Repository files navigation

@sbaiahmed1/react-native-blur

Demo

Requirements

⚠️ Breaking Changes in v4.0.0

What Changed

Migration from 3.x to 4.0.0

Why This Change?

Summary

Features

Comparison with Other Libraries

Key Advantages

vs. @react-native-community/blur

vs. expo-blur

Migration Guide

From @react-native-community/blur

From expo-blur

Installation

iOS Setup

Android Setup

Usage

BlurView - Standard Blur Effects

Basic Usage

Advanced Blur Usage

ProgressiveBlurView - Variable/Gradient Blur

Locked Content Example

LiquidGlassView - Liquid Glass Effects (iOS 26+)

Interactive Liquid Glass

Props

BlurView Props

ProgressiveBlurView Props

LiquidGlassView Props

Blur Types (BlurView)

Glass Types (LiquidGlassView)

Platform Differences

iOS

BlurView

LiquidGlassView

Android

BlurView

LiquidGlassView

Accessibility

BlurView

LiquidGlassView

TypeScript Support

Example App

Performance Considerations

BlurView

LiquidGlassView

General Tips

What's New in v4.0.0

🎯 Component Separation (BREAKING CHANGE)

🌊 Liquid Glass Effects (iOS 26+)

🔄 SwiftUI Rewrite

📱 Enhanced Example App

🛠️ Developer Experience

Contributing

License

📊 Stats

Credits

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Contributors 6

Languages

Packages