◐react-native-blur

Migration & breaking changes

Breaking changes in v5.0.0

New Architecture is now required

The library ships Fabric components only and no longer includes the legacy (Paper) view managers. You must be on React Native 0.76+ with the New Architecture enabled. peerDependencies now require react-native >= 0.76.0 and react >= 18.2.0 (previously unpinned).

There is no code change to make in your app beyond being on a supported New Architecture setup — if you were already on it (which prior versions effectively required), nothing else changes.

Raw native components are deprecated

The raw ReactNative* codegen components (ReactNativeBlurView, ReactNativeLiquidGlassView, and friends) are still exported but now marked @deprecated and will be removed in a future major. Always use the wrapper components (BlurView, LiquidGlassView, …), which handle platform fallbacks, defaults and refs:

// Deprecated — do not import the raw native component
import { ReactNativeBlurView } from '@sbaiahmed1/react-native-blur';

// Use the wrapper instead
import { BlurView } from '@sbaiahmed1/react-native-blur';

Android BlurSwitch blur strength

On Android, BlurSwitch now maps blurAmount to the same strength as BlurView and ProgressiveBlurView (previously it rendered a weaker blur for the same value). If you tuned blurAmount on a BlurSwitch for a specific look, re-check it.

New: ref forwarding

Not breaking, but new in v5: BlurView, ProgressiveBlurView, VibrancyView, LiquidGlassView and LiquidGlassContainer now forward a ref to their underlying native view (on the primary platform path).

Breaking changes in v4.0.0

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

// v3.x — deprecated
<BlurView
  type="blur" // or "liquidGlass"
  blurType="light"
  blurAmount={10}
  glassType="regular"
  glassTintColor="#007AFF"
/>

v4.0.0 separated this into two dedicated components:

// v4.0.0+
import { BlurView, LiquidGlassView } from '@sbaiahmed1/react-native-blur';

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

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

Why the split

  • Cleaner APIs — each component only exposes props relevant to its own effect.
  • Better tree-shaking — import only what you use.
  • Type safety — separate TypeScript definitions prevent mixing incompatible props.
  • Clearer code — explicit about which effect is being used.

Migrating from 3.x

// Before
<BlurView type="blur" blurType="light" blurAmount={10} />
// After
<BlurView blurType="light" blurAmount={10} />
// Before
<BlurView type="liquidGlass" glassType="regular" glassTintColor="#007AFF" glassOpacity={0.8} />
// After
import { LiquidGlassView } from '@sbaiahmed1/react-native-blur';
<LiquidGlassView glassType="regular" glassTintColor="#007AFF" glassOpacity={0.8} />

Migrating from @react-native-community/blur

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

// After — same shape, now with a dedicated glass component available too
import { BlurView, LiquidGlassView } from '@sbaiahmed1/react-native-blur';

<BlurView blurType="light" blurAmount={10} />
<LiquidGlassView glassType="regular" glassTintColor="#007AFF" glassOpacity={0.8} />

Migrating 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:

  1. npm uninstall @react-native-community/blur expo-blur
  2. npm install @sbaiahmed1/react-native-blur
  3. Update imports
  4. cd ios && pod install

Release history

There is no CHANGELOG.md in the repository yet — release notes currently live in GitHub Releases and tags. The most notable recent addition is LiquidGlassContainer (v4.1.2), which groups LiquidGlassView elements with configurable spacing via iOS 26+’s UIGlassContainerEffect.

← Props reference