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

A simple blur view in react native based on @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 and sticky header component aren't supported in Android. For more information, just click here!

Note

This package supports only new architecture.

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';
// ...

export default function App() {
  const targetRef = useRef<View | null>(null);
  // ...

  return (
    <>
      <BlurView blurTarget={targetRef} style={styles.blurView}>
        <Text style={styles.text}>BlurView</Text>
      </BlurView>

      <VibrancyView style={styles.vibrancyView}>
        <Text style={styles.text}>VibrancyView</Text>
      </VibrancyView>

      <BlurTarget ref={targetRef} style={styles.blurTarget}>
        <ScrollView
          style={styles.scrollView}
          contentContainerStyle={styles.contentContainer}
          showsVerticalScrollIndicator={false}
        >
          {/* ... */}
        </ScrollView>
      </BlurTarget>
    </>
  );
}

export const styles = 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 the list, and the content behind should be added as a 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';
// ...

export function MyScreen() {
  const targetRef = useRef<View | null>(null);
  // ...

  return (
    <View style={styles.container}>
      <BlurTarget ref={targetRef} style={styles.blurTarget}>
        <ImageBackground
          style={styles.background}
          source={BACKGROUND}
          resizeMode="cover"
        />
      </BlurTarget>

      <ScrollView
        style={styles.scrollView}
        contentContainerStyle={styles.contentContainer}
        showsVerticalScrollIndicator={false}
      >
        <BlurView blurTarget={targetRef} style={styles.blurView}>
          <Text style={styles.text}>BlurView 1</Text>
        </BlurView>

        <BlurView blurTarget={targetRef} style={styles.blurView}>
          <Text style={styles.text}>BlurView 2</Text>
        </BlurView>

        <BlurView blurTarget={targetRef} style={styles.blurView}>
          <Text style={styles.text}>BlurView 3</Text>
        </BlurView>

        {/* ... */}
      </ScrollView>
    </View>
  );
}

Using `Modal`

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

import { useRef, useState } from 'react';
import { Modal, View } from 'react-native';
import { BlurTarget, BlurView } from '@danielsaraldi/react-native-blur-view';
// ...

export function MyScreen() {
  const [isOpenModal, setIsOpenModal] = useState<boolean>(false);
  const targetRef = useRef<View | null>(null);
  // ...

  return (
    <>
      <Modal
        transparent
        statusBarTranslucent
        navigationBarTranslucent
        hardwareAccelerated
        visible={isOpenModal}
        onRequestClose={() => setIsOpenModal(false)}
        style={styles.modal}
      >
        <BlurView blurTarget={targetRef} style={styles.blurView} />

        <View style={styles.modalContent}>{/* ... */}</View>
      </Modal>

      <BlurTarget ref={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 used as a sibling of BlurTarget for the blur effect to work correctly.

import { useRef } from 'react';
import { ImageBackground, View } from 'react-native';
import { BlurTarget, BlurView } from '@danielsaraldi/react-native-blur-view';
// ...

export function MyScreen() {
  const targetRef = useRef<View | null>(null);
  // ...

  return (
    <>
      <View style={styles.blurViewWrapper}>
        <BlurView
          blurTarget={targetRef}
          style={styles.blurView}
          downscaleFactor={4}
        >
          {/** ... **/}
        </BlurView>
      </View>

      <BlurTarget ref={targetRef} style={styles.blurTarget}>
        <ImageBackground
          style={styles.background}
          source={{ uri: 'https://picsum.photos/seed/picsum/600/900' }}
          resizeMode="cover"
        />
      </BlurTarget>
    </>
  );
}

Components

`BlurView`

The BlurView component extends the same properties of a View component. The blurTarget prop is required for the Android blur effect to work 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`.	`20.0`	All
`downscaleFactor`	Downscale factor `0` - `100`.	`6.0`	Android
`overlayColor`	Add the overlay color to the component.	`undefined`	All
`androidColor`	Overrides the `type` property color.	`undefined`	Android
`reducedTransparencyFallbackColor`	Background color for the blur effect when reduced transparency is enabled.	`white`	iOS

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

`BlurTarget`

The BlurTarget component extends the same properties of 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 extends the same properties of 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`.	`20.0`	iOS
`overlayColor`	Add the overlay color to the component.	`undefined`	iOS
`reducedTransparencyFallbackColor`	Background color for the vibrancy effect when reduced transparency is enabled.	`white`	iOS

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

Types

These are all available types.

Blur Types

On iOS, all types are supported, but on Android, the types are simulated 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. (iOS >= 10)	All
`prominent`	A blur style for making content more prominent that adapts to the user interface style. (iOS >= 10)	All
`chrome-material`	An adaptable blur effect that creates the appearance of the system chrome. (iOS >= 13)	All
`material`	An adaptable blur effect that creates the appearance of a material with normal thickness. (iOS >= 13)	All
`thick-material`	An adaptable blur effect that creates the appearance of a material that’s thicker than normal. (iOS >= 13)	All
`thin-material`	An adaptable blur effect that creates the appearance of a thin material. (iOS >= 13)	All
`ultra-thin-material`	An adaptable blur effect that creates the appearance of an ultra-thin material. (iOS >= 13)	All
`chrome-material-light`	A blur effect that creates the appearance of the system chrome and is always light. (iOS >= 13)	All
`material-light`	A blur effect that creates the appearance of a material with normal thickness and is always light. (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. (iOS >= 13)	All
`thin-material-light`	A blur effect that creates the appearance of a thin material and is always light. (iOS >= 13)	All
`ultra-thin-material-light`	A blur effect that creates the appearance of an ultra-thin material and is always light. (iOS >= 13)	All
`chrome-material-dark`	A blur effect that creates the appearance of the system chrome and is always dark. (iOS >= 13)	All
`material-dark`	A blur effect that creates the appearance of a material with normal thickness and is always dark. (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. (iOS >= 13)	All
`thin-material-dark`	A blur effect that creates the appearance of a thin material and is always dark. (iOS >= 13)	All
`ultra-thin-material-dark`	A blur effect that creates the appearance of an ultra-thin material and is always dark. (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
<BlurView blurTarget={targetRef} type='x-light' style={styles.blurView}>
  {/** ... **/}
</BlurView>

<VibrancyView blurTarget={targetRef} type='x-light' style={styles.vibrancyView}>
  {/** ... **/}
</VibrancyView>

// ✅ New API (v3.0.0) - Current
<BlurView blurTarget={targetRef} type='extra-light' style={styles.blurView}>
  {/** ... **/}
</BlurView>

<VibrancyView blurTarget={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
<BlurView blurTarget={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 regular, prominent, and material blur types, the overlay color opacity is scaled by radius / 100 to match the iOS effect intensity. This doesn't apply when androidColor is provided.

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-tabs and sticky header component aren't supported! If you want to customize your bottom tabs or sticky header component, opt for @sbaiahmed1/react-native-blur.

Only components based on TextureView are supported. Components that use SurfaceView aren't supported by the BlurView third-party library.

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.

For regular, prominent, and material blur types, the radius property controls the strength of the whole effect (blur, tint, and saturation) as a percentage (radius / 100), since these types don't support a custom blur radius. A radius of 100 keeps the native strength of the blur type, which can't be exceeded.

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 styles aren't supported.

Expo

In Expo, you need to convert to a custom development build or use prebuild. You can also use 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';

export const INITIAL_BLUR_TYPE: BlurType = 'light';
export const INITIAL_EFFECT_STYLE: EffectStyle = 'label';

export interface CustomBlurViewProps extends BlurViewProps {
  // ...
}

export interface CustomBlurTargetProps extends BlurTargetProps {
  // ...
}

export interface CustomVibrancyViewProps extends VibrancyProps {
  // ...
}

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 liquid glass.
🛑 @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 ❤️

Name		Name	Last commit message	Last commit date
.github		.github
.yarn		.yarn
android		android
example		example
ios		ios
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.nvmrc		.nvmrc
.watchmanconfig		.watchmanconfig
.yarnrc.yml		.yarnrc.yml
BlurView.podspec		BlurView.podspec
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
eslint.config.mjs		eslint.config.mjs
lefthook.yml		lefthook.yml
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
yarn.lock		yarn.lock

Navigation Menu

Repository navigation

About

Repository files navigation

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

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

tvOS

Expo

TypeScript Support

Others Libraries

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

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

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

tvOS

Expo

TypeScript Support

Others Libraries

Contributing

License

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

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

Using `Modal`

Using `ImageBackground`

`BlurView`

`BlurTarget`

`VibrancyView`