◐react-native-blur

Migration & breaking changes

Breaking changes in v6.0.0

New: native liquid glass on Android 13+

Not a breaking change, but the headline of 6.0: LiquidGlassView now renders real liquid glass on Android 13+ (AGSL RuntimeShader — refraction, dispersion, blur and shader-modulated tint) instead of the tinted-blur approximation. No code changes needed — the same props apply; Android below 13 (and iOS below 26) keep the automatic BlurView fallback. If a screen mounts many glass views, read the memory guidance first.

ProgressiveBlurView startOffset is now cross-platform consistent

startOffset now means the same thing on every platform: for the edge directions it grows the fully-blurred plateau from the blurred edge (the fade spans the rest of the view); for the center direction it insets the fade start from the edges (clamped to 0.3), shortening the blur body.

Previously, iOS interpreted the edge directions inversely — startOffset grew the fully-clear region from the clear edge — so the same value produced opposite fade geometry per platform (e.g. a startOffset={0.6} bottom paywall blur hid content on Android/Web but left it readable on iOS). Web’s center direction also grew the blurred band instead of shrinking it.

What to do: if you tuned startOffset on iOS, or used Platform.select to paper over the difference, collapse it to one value and re-check the fade. As a rule of thumb, an old iOS value x corresponds roughly to a new value of 1 - x minus the intended fade span. startOffset={0} (the default) is unchanged on all platforms.

Android’s fade curve was also retuned in this release (eased instead of linear) so the default renders a visible blur body — see issue #119.

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.80+ with the New Architecture enabled. peerDependencies now require react-native >= 0.80.0 and react >= 18.2.0. The 0.80 floor comes from the codegen specs importing codegenNativeComponent from the react-native root (the deep react-native/Libraries/... import paths are deprecated), which older versions don’t export.

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