Blur
@symbiote-native/blur wraps expo-blur,
a native view that blurs the content behind it, so every SymbioteNative adapter can reach it, not
just React. BlurView paints the blur, BlurTargetView marks the content Android blurs.
Installation
Section titled “Installation”npm install @symbiote-native/blurScaffolding or extending a SymbioteNative app? npx @symbiote-native/cli new --blur (or
add --blur in an existing app) installs and wires this for you.
On Android the dimezis blur methods need a blurTarget, the BlurTargetView whose content is
blurred. Without one BlurView falls back to none and warns. iOS ignores the target.
import { BlurTargetView, BlurView } from '@symbiote-native/blur/react';
const target = useRef<IHostInstance>(null);
<BlurTargetView ref={target}> <Image source={photo} /></BlurTargetView>;<BlurView blurTarget={target} blurMethod="dimezisBlurView" tint="light" intensity={60}> <Text>Over the blur</Text></BlurView>;<script setup lang="ts">import { ref } from '@vue/runtime-core';import { BlurTargetView, BlurView } from '@symbiote-native/blur/vue';
const target = ref(null);</script>
<template> <BlurTargetView ref="target"><image :source="photo" /></BlurTargetView> <BlurView :blur-target="target" blur-method="dimezisBlurView" tint="light" :intensity="60"> <text>Over the blur</text> </BlurView></template><script lang="ts"> import { BlurTargetView, BlurView } from '@symbiote-native/blur/svelte';
let target = $state<unknown>();</script>
<BlurTargetView bind:ref={target}><image source={photo} /></BlurTargetView><BlurView blurTarget={target} blurMethod="dimezisBlurView" tint="light" intensity={60}> <text>Over the blur</text></BlurView>import { createSignal } from 'solid-js';import { BlurTargetView, BlurView } from '@symbiote-native/blur/solid';
const [target, setTarget] = createSignal<IHostInstance>();
<BlurTargetView ref={setTarget}><image source={photo} /></BlurTargetView>;<BlurView blurTarget={target()} blurMethod="dimezisBlurView" tint="light" intensity={60}> <text>Over the blur</text></BlurView>;import { BlurTargetView, BlurView } from '@symbiote-native/blur/angular';
@Component({ imports: [BlurTargetView, BlurView], template: ` <BlurTargetView #target><image [source]="photo" /></BlurTargetView> <BlurView [blurTarget]="target" blurMethod="dimezisBlurView" tint="light" [intensity]="60"> <text>Over the blur</text> </BlurView> `,})export class Card {}| Prop | Description |
|---|---|
tint |
default, light, dark, extraLight, regular, system materials |
intensity |
1 to 100, default 50 |
blurMethod |
Android: none, dimezisBlurView, dimezisBlurViewSdk31Plus |
blurReductionFactor |
Android divider of the intensity, default 4 |
blurTarget |
The framework’s reference to a BlurTargetView, Android |
Plus style, testID, nativeID, onLayout and the accessibility and responder props every View
takes. Not ported: the web variant and the Reanimated getAnimatableRef hook.
- Android blurs nothing until you ask for it.
blurMethoddefaults tonone, which is only a translucent view. PickdimezisBlurView(ordimezisBlurViewSdk31Plus) and pass ablurTarget. Without a target the package warns and falls back tonone. - One
BlurTargetViewcan serve manyBlurViews, as long as they all sit inside its bounds. That is cheaper than one target per blur. - The blur view must be above what it blurs. Place it after the content in the tree (or give it
a higher
zIndex), not beside or under it. - Every iOS tint adds a translucent layer. Each
tintis a system material that sits over the blur, and iOS exposes no plain blur radius. Android and the fallback can go without a tint. blurReductionFactoris Android only. It divides the intensity to bring the Android blur closer to iOS.- Without the native view you get a plain
View. The package logsBlurView is not available on this platformand renders your children without a blur.
Common questions
Section titled “Common questions”Nothing is blurred on Android. The default blurMethod is none. Wrap the content in a
BlurTargetView, pass its ref as blurTarget and set blurMethod="dimezisBlurView". If the
blurTarget is missing, the package warns and falls back to none.
The blur does not follow a scrolling list. The blur view has to be rendered after the content it
covers, as a later sibling or with a higher zIndex. A blur placed beside or below the list shows
the list unblurred. Keep tint at default to drop the light wash.
How do I blur inside a Modal on Android? A Modal is a separate native window, so the blur
view inside it cannot reach a target that lives outside. The layout the Expo team confirmed puts the
Modal itself inside the BlurTargetView, with the BlurView inside the Modal pointing at that
target. Upstream will not bring back the old method that blurred the whole window, it is far slower.
This layout is not demoed in the canary apps, so test it on your adapter before relying on it.
Corners are not rounded. borderRadius alone does not clip the blur. Put overflow: 'hidden'
in the same style, or wrap the blur in a view that has the radius and overflow: 'hidden'.
The blur is missing on some iPhones. Check Settings > Accessibility > Display & Text Size > Reduce Transparency. When it is on, iOS turns blur effects off. It can differ between two phones of the same model, so a user report of a missing blur is often this switch. Render a solid translucent fallback for those users.
Can I get a blur with no tint? On iOS, no: every system blur style composes a tint layer over the backdrop and the public API has no plain blur radius. Upstream documented this instead of changing it.
Can I animate intensity? intensity is an ordinary prop, so drive it from state, a signal or a
rune. Animating it through Reanimated’s animatedProps was broken on the New Architecture by a
Reanimated bug, since fixed there. SymbioteNative does not ship the Reanimated getAnimatableRef
hook.
The Android build says it cannot find BlurView. The native blur comes from the
com.github.Dimezis:BlurView library on JitPack, and React Native’s Gradle plugin adds JitPack to
every project by default. The build fails if you set react.includeJitpackRepository=false in
gradle.properties, or if JitPack served a broken build of the pinned version, which happened to
BlurView 2.0.3. In that case update expo-blur through the package rather than pinning the library
by hand.
Sources:
- Expo docs: BlurView
- expo/expo#6613 BlurView does not update the blur
- expo/expo#44165 BlurView inside a Modal on Android
- expo/expo#18615 borderRadius on expo-blur
- expo/expo#34737 blur missing on a physical device
- expo/expo#49240 no option to render a blur without a tint
- expo/expo#32781 animating BlurView intensity with Reanimated
- expo/expo#34141 Android build cannot find BlurView 2.0.3
How the wrapper works
Section titled “How the wrapper works”expo-blur’s JS is hand-ported into this package’s core/: the props, the blurMethod warning
and the descriptors. renderBlurView returns a View that carries your style with an
absolute-fill native blur inside it, on both platforms, and renderBlurTargetView returns the
native target on Android and a plain View on iOS. blurTarget is each adapter’s own reference to
a BlurTargetView: the package resolves it to a node and waits for the commit before telling
native, so a Vue or Svelte render order cannot hand native a tag that does not exist yet. The native
code is never vendored: expo-modules-autolinking resolves it from node_modules (see
the native setup guide).