@danielsaraldi/react-native-blur-view 🌫️

A simple blur view in react native based in @react-native-community/blur.

Support the animation transitions with react-native-screens, react-native-reanimated, react-native-navigation and Modals 😁. This library supports Apple TV and Android TV! 📺

Warning

Bottom tabs customized with the react-navigation/bottom-tabs aren't supported in Android. For more information, just click here!

Note

This package supports onlynew architecture.

Summary

• Installation
• Usage
  • Using lists
  • Using Modal
  • Using ImageBackground
• Components
  • BlurView
    • Properties
  • BlurTarget
    • Properties
  • VibrancyView
    • Properties
• Types
  • Blur Types
  • Effect Styles
• Migrate to 3.x
  • Why This Change?
• Platform Differences
  • Android
  • iOS
• Expo
• TypeScript Support
• Others Libraries
• Contributing
• License

Installation

npm install @danielsaraldi/react-native-blur-view
# or
yarn add @danielsaraldi/react-native-blur-view
# or
pnpm add @danielsaraldi/react-native-blur-view
# or
bun add @danielsaraldi/react-native-blur-view

Install native dependencies (iOS only):

cd ios && pod install &&cd ..

Usage

import{useRef}from'react';import{ScrollView,StyleSheet,Text,View}from'react-native';import{BlurView,BlurTarget,VibrancyView,}from'@danielsaraldi/react-native-blur-view';// ...exportdefaultfunctionApp(){consttargetRef=useRef<View|null>(null);// ...return(<><BlurViewblurTarget={targetRef}style={styles.blurView}><Textstyle={styles.text}>BlurView</Text></BlurView><VibrancyViewstyle={styles.vibrancyView}><Textstyle={styles.text}>VibrancyView</Text></VibrancyView><BlurTargetref={targetRef}style={styles.blurTarget}><ScrollViewstyle={styles.scrollView}contentContainerStyle={styles.contentContainer}showsVerticalScrollIndicator={false}>{/* ... */}</ScrollView></BlurTarget></>);}exportconststyles=StyleSheet.create({blurView: {position: 'absolute',top: 0,width: '100%',height: 256,justifyContent: 'center',alignItems: 'center',},vibrancyView: {position: 'absolute',top: 256,width: '100%',height: 256,justifyContent: 'center',alignItems: 'center',},title: {fontSize: 24,fontWeight: 'bold',color: 'white',},main: {flex: 1,},content: {padding: 20,gap: 8,},});

Using lists

You must add BlurView elements inside of the list, and the content behind should be added as child of the BlurTarget component. Check an example using ScrollView below:

import{useRef}from'react';import{ImageBackground,ScrollView,Text,View}from'react-native';import{BlurView,BlurTarget}from'@danielsaraldi/react-native-blur-view';// ...exportfunctionMyScreen(){consttargetRef=useRef<View|null>(null);// ...return(<Viewstyle={styles.container}><BlurTargetref={targetRef}style={styles.blurTarget}><ImageBackgroundstyle={styles.background}source={BACKGROUND}resizeMode="cover"/></BlurTarget><ScrollViewstyle={styles.scrollView}contentContainerStyle={styles.contentContainer}showsVerticalScrollIndicator={false}><BlurViewblurTarget={targetRef}style={styles.blurView}><Textstyle={styles.text}>BlurView 1</Text></BlurView><BlurViewblurTarget={targetRef}style={styles.blurView}><Textstyle={styles.text}>BlurView 2</Text></BlurView><BlurViewblurTarget={targetRef}style={styles.blurView}><Textstyle={styles.text}>BlurView 3</Text></BlurView>{/* ... */}</ScrollView></View>);}

Using Modal

You must add BlurTarget as a parent of content screen because it will be the target of blur, the BlurView component must be to used inside of Modal to blur effect works correctly.

import{useRef,useState}from'react';import{Modal,View}from'react-native';import{BlurTarget,BlurView}from'@danielsaraldi/react-native-blur-view';// ...exportfunctionMyScreen(){const[isOpenModal,setIsOpenModal]=useState<boolean>(false);consttargetRef=useRef<View|null>(null);// ...return(<><ModaltransparentstatusBarTranslucentnavigationBarTranslucenthardwareAcceleratedvisible={isOpenModal}onRequestClose={()=>setIsOpenModal(false)}style={styles.modal}><BlurViewblurTarget={targetRef}style={styles.blurView}/><Viewstyle={styles.modalContent}>{/* ... */}</View></Modal><BlurTargetref={targetRef}style={styles.blurTarget}>{/* ... */}</BlurTarget></>);}

Using ImageBackground

You must add BlurTarget as a parent of ImageBackground because it will be the target of blur, the BlurView component must be to used as brother of BlurTarget to blur effect works correctly.

import{useRef}from'react';import{ImageBackground,View}from'react-native';import{BlurTarget,BlurView}from'@danielsaraldi/react-native-blur-view';// ...exportfunctionMyScreen(){consttargetRef=useRef<View|null>(null);// ...return(<><Viewstyle={styles.blurViewWrapper}><BlurViewblurTarget={targetRef}style={styles.blurView}downscaleFactor={4}>{/** ... **/}</BlurView></View><BlurTargetref={targetRef}style={styles.blurTarget}><ImageBackgroundstyle={styles.background}source={{uri: 'https://picsum.photos/seed/picsum/600/900'}}resizeMode="cover"/></BlurTarget></>);}

Components

BlurView

The BlurView component is an extends the same properties of the a View component. The blurTarget prop is required for Android blur effect works correctly.

Properties

Property	Description	Default	Platform
blurTarget	Ref of the BlurTarget component to be identified by the BlurView component in the tree.	undefined	Android
type	Blur type of the overlay.	light	All
radius	Blur radius 0 - 100.	10.0	All
downscaleFactor	Downscale factor 0 - 100.	6.0	Android
overlayColor	Add the overlay color about component.	undefined	All
androidColor	Overrides the type property color.	undefined	Android
reducedTransparencyFallbackColor	Background color about blur effect when reduced transparency is enabled.	white	iOS

When a value less than 0 or greater than 100 are provided for radius or downscaleFactor property, the value is clipped.

BlurTarget

The BlurTarget component is an extends the same properties of the a View component.

This component is available for Android only. It's useful because we use Dimezis's 3v library to apply the blur effect, so its implementation is slightly different than on iOS. The BlurTarget component is a common View in iOS.

The BlurTarget may not contain a BlurView that targets the same BlurTarget. The BlurTarget may contain other BlurTargets and BlurViews though.

Properties

Property	Description	Default	Platform
ref	Ref of the BlurTarget component to be identified by the BlurView component in the tree.	undefined	Android

VibrancyView

The VibrancyView component is an extends the same properties of the a View component.

This component is available for iOS only. It applies a vibrancy effect to child content. On Android, the VibrancyView component is a common View. The effectStyle property isn't supported on tvOS.

Properties

Property	Description	Default	Platform
type	Blur type of the overlay.	light	iOS
effectStyle	Effect style to vibrancy content.	label	iOS
radius	Blur radius 0 - 100.	10	iOS
overlayColor	Add the overlay color about component.	undefined	iOS
reducedTransparencyFallbackColor	Background color about vibrancy effect when reduced transparency is enabled.	white	iOS

When a value less than 0 or greater than 100 are provided for radius property, the radius is clipped.

Types

These are all types of available.

Blur Types

On iOS all types are supported, but, on Android is simulated the types using RGBA colors.

Property	Description	Platform
extra-light	The area of the view is lighter than the underlying view.	All
light	The area of the view is the same approximate lightness of the underlying view.	All
dark	The area of the view is darker than the underlying view.	All
extra-dark	The area of the view is even more dark than the underlying view. (tvOS >= 10)	All
regular	A regular blur style that adapts to the user interface style. Radius doesn't apply to this. (iOS >= 10)	All
prominent	A blur style for making content more prominent that adapts to the user interface style. Radius doesn't apply to this. (iOS >= 10)	All
chrome-material	An adaptable blur effect that creates the appearance of the system chrome. Radius doesn't apply to this. (iOS >= 13)	All
material	An adaptable blur effect that creates the appearance of a material with normal thickness. Radius doesn't apply to this. (iOS >= 13)	All
thick-material	An adaptable blur effect that creates the appearance of a material that’s thicker than normal. Radius doesn't apply to this. (iOS >= 13)	All
thin-material	An adaptable blur effect that creates the appearance of a thin material. Radius doesn't apply to this. (iOS >= 13)	All
ultra-thin-material	An adaptable blur effect that creates the appearance of an ultra-thin material. Radius doesn't apply to this. (iOS >= 13)	All
chrome-material-light	A blur effect that creates the appearance of the system chrome and is always light. Radius doesn't apply to this. (iOS >= 13)	All
material-light	A blur effect that creates the appearance of a material with normal thickness and is always light. Radius doesn't apply to this. (iOS >= 13)	All
thick-material-light	A blur effect that creates the appearance of a material that’s thicker than normal and is always light. Radius doesn't apply to this. (iOS >= 13)	All
thin-material-light	A blur effect that creates the appearance of a thin material and is always light. Radius doesn't apply to this. (iOS >= 13)	All
ultra-thin-material-light	A blur effect that creates the appearance of an ultra-thin material and is always light. Radius doesn't apply to this. (iOS >= 13)	All
chrome-material-dark	A blur effect that creates the appearance of the system chrome and is always dark. Radius doesn't apply to this. (iOS >= 13)	All
material-dark	A blur effect that creates the appearance of a material with normal thickness and is always dark. Radius doesn't apply to this. (iOS >= 13)	All
thick-material-dark	A blur effect that creates the appearance of a material that’s thicker than normal and is always dark. Radius doesn't apply to this. (iOS >= 13)	All
thin-material-dark	A blur effect that creates the appearance of a thin material and is always dark. Radius doesn't apply to this. (iOS >= 13)	All
ultra-thin-material-dark	A blur effect that creates the appearance of an ultra-thin material and is always dark. Radius doesn't apply to this. (iOS >= 13)	All

Learn more about blur types here.

Effect Styles

On iOS all effect styles are supported. This property is available in the VibrancyView component, it's iOS only.

Property	Description	Platform
label	A style for labels containing primary content. (iOS >= 13)	iOS
secondary-label	A style for labels containing secondary content. (iOS >= 13)	iOS
tertiary-label	A style for labels containing tertiary content. (iOS >= 13)	iOS
quaternary-label	A style for labels containing quaternary content. (iOS >= 13)	iOS
fill	A style for views with large filled areas containing primary content. (iOS >= 13)	iOS
secondary-fill	A style for views with large filled areas containing secondary content. (iOS >= 13)	iOS
tertiary-fill	A style for views with large filled areas containing tertiary content. (iOS >= 13)	iOS
separator	A style for separator lines. (iOS >= 13)	iOS

• Label styles show progressive opacity drops from full white to near-invisible.
• Fill styles show translucent rectangles at decreasing opacity levels.
• Separator style is specifically for thin, translucent separator lines.

Learn more about effect styles here.

Migrate to 3.x

Warning

Version 3.0.0 introduces significant API changes on Android and iOS applications. If you're upgrading from 2.x, please read this section carefully.

In version 3.0.0, the x-light blur type has been renamed to extra-light in the BlurView and VibrancyView components:

// ❌ Old API (v2.x) - Deprecated<BlurViewblurTarget={targetRef}type='x-light'style={styles.blurView}>{/** ... **/}</BlurView><VibrancyViewblurTarget={targetRef}type='x-light'style={styles.vibrancyView}>{/** ... **/}</VibrancyView>// ✅ New API (v3.0.0) - Current<BlurViewblurTarget={targetRef}type='extra-light'style={styles.blurView}>{/** ... **/}</BlurView><VibrancyViewblurTarget={targetRef}type='extra-light'style={styles.vibrancyView}>{/** ... **/}</VibrancyView>

A new type of blur called extra-dark has been added to the BlurView and VibrancyView components, below is a small example:

// ✅ New type (v3.0.0) - Current<BlurViewblurTarget={targetRef}type="extra-dark"style={styles.blurView}>{/** ... **/}</BlurView>

Why This Change?

This version focused exclusively on full TV device support. The main changes are listed below:

• New support: Added full support for Android TV and Apple TV.
• Types: The BlurView and VibrancyView component types have undergone minor changes:
  • Renaming: Renamed x-light to extra-light.
  • New type: Added a new extra-dark type.
• Runtime: Bump Node.js version from 20.x to 22.x.

Platform Differences

Android

On Android platforms, the component utilizes the BlurView library to offer native blur effects with hardware-accelerated rendering.

For different types of extra-light, light, dark and extra-dark, the radius is fixed at 35. This is done to maintain similarity with the iOS effect.

The androidColor property can be useful when you want to achieve a specific look or match the blur effect to other elements in your app. It overrides the type property.

Bottom tabs customized with the react-navigation/bottom-tabsaren't supported! If you want to customize your bottom tabs, opt for @sbaiahmed1/react-native-blur.

iOS

On iOS all types are supported by default. However, on Android they are RGBA colors to simulate the same blur color.

The extra-dark blur type is not natively available on iOS, so it falls back to the dark blur type.

tvOS

On tvOS, the blur types extra-light, light, dark, extra-dark, regular, and prominent are supported. Other blur types are accepted by the API but fall back to the light blur type on tvOS, since the underlying UIBlurEffectStyle values are unavailable.

The effect stylesaren't supported.

Expo

In Expo, you need to convert to a custom development build or use prebuild. You can use also React Native without Expo.

TypeScript Support

Full TypeScript support with proper type definitions!

import{BlurType,EffectStyle,BlurViewProps,BlurTargetProps,VibrancyProps,}from'@danielsaraldi/react-native-blur-view';exportconstINITIAL_BLUR_TYPE: BlurType='light';exportconstINITIAL_EFFECT_STYLE: EffectStyle='label';exportinterfaceCustomBlurViewPropsextendsBlurViewProps{// ...}exportinterfaceCustomBlurTargetPropsextendsBlurTargetProps{// ...}exportinterfaceCustomVibrancyViewPropsextendsVibrancyProps{// ...}

Others Libraries

• ✅ expo-blur - A React component that blurs everything underneath the view. Common usage of this is for navigation bars, tab bars, and modals.
• ✅ @sbaiahmed1/react-native-blur - A modern React Native blur view component that provides native blur effects for both iOS and Android platforms. also adds progressive blur and liquidGlass.
• 🛑 @react-native-community/blur - A component for UIVisualEffectView's blur and vibrancy effect on iOS, and BlurView on Android.

Contributing

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

License

MIT

---

Made with create-react-native-library ❤️