react-native-figma-blur
v0.1.1
Published
Figma-identical blur and Liquid Glass for React Native. One sigma model, two GPU backends, zero jank.
Downloads
26
Maintainers
Readme
| iOS 26 · iPhone 17 Pro | Android 16 · Pixel 6 |
|---|---|
|
|
|
Install
npm install react-native-figma-bluryarn add react-native-figma-blurThen rebuild the app — this package ships native code, so a Metro reload will not pick it up:
cd ios && pod install && cd .. # iOS only
npm run ios # or: npm run androidRequirements: React Native 0.76+ with the New Architecture, iOS 15.1+, Android 7.0+ (blur is active on Android 12 / API 31 and up — see Platform support).
Your first blur
import { FigmaBlurView } from 'react-native-figma-blur';
<FigmaBlurView blurRadius={40} style={{ borderRadius: 24, padding: 20 }}>
<Text>Sharp text on a blurred backdrop</Text>
</FigmaBlurView>That is the whole idea: blurRadius is the number from Figma's inspector.
Paste it in. You do not convert it, and you do not tune it per platform.
Two things to know straight away:
- Put it over something. A backdrop blur shows what is painted behind it, so with nothing behind it there is nothing to see.
- Use
tintColor, notbackgroundColor. The blur sits above the background and would hide it.
<FigmaBlurView
blurRadius={40}
tintColor="rgba(255,255,255,0.45)" // the fill from your Figma layer
style={{ borderRadius: 24, padding: 20 }}
>
<Text>Now it looks like the mock</Text>
</FigmaBlurView>Ready-made materials
If you just want a good-looking panel, start here instead of picking numbers:
import { FigmaBlurView, Materials } from 'react-native-figma-blur';
<FigmaBlurView {...Materials.thin} style={{ borderRadius: 24 }} />ultraThin · thin · regular · thick, each with a …Dark counterpart.
These are the recipes designers actually draw — a background blur plus a translucent fill — so they match the mock rather than matching UIKit.
Liquid Glass
import { GlassView } from 'react-native-figma-blur';
<GlassView variant="regular" style={{ borderRadius: 28, height: 60 }}>
<Text>Glass</Text>
</GlassView>On iOS 26+ this is the platform's own glass material. On Android it is synthesised in a runtime shader — edge refraction, specular rim and all — and colour-matched to iOS in both light and dark mode.
The blur scale
blurRadius is a Figma value; sigma is the Gaussian it resolves to. The grid
behind these tiles is there to be destroyed — it is what makes one step
distinguishable from the next.
| iOS | Android |
|---|---|
|
|
|
Why not just use a blur library?
Three things go wrong when you try to match a Figma mock on both platforms, and they compound:
- Every layer speaks a different unit. Figma's blur value is 2× the sigma.
CSS
blur()is the sigma. Android'sRenderEffecttakes a Skia radius. Core Animation takes another. Pass the same number to each and you get four different blurs. - iOS materials saturate.
UIBlurEffectboosts backdrop saturation by roughly 1.8×; Figma does not. This is why a stock iOS blur looks wrong beside the mock, and no amount of radius tuning fixes it. - Downscaling softens. The standard performance trick overshoots, because blurs compose in variance rather than sigma.
This library defines blur once — as a sigma — and converts per platform at the last step. How it works has the detail.
And it is measured, not asserted. At blurRadius={40}:
| | measured sigma | vs model (20.0) | |---|---|---| | iOS — iPhone 17 Pro | 19.59 dip | −2.1% | | Android — Pixel 6 | 20.16 dip | +0.8% | | difference | | 2.9% |
You can run the check yourself: npm run parity.
How it compares
Checked by reading each package's published source — versions inspected are expo-blur 57.0.2 and @react-native-community/blur 4.4.1.
| | this | @react-native-community/blur | expo-blur |
|---|---|---|---|
| You specify | Figma blur value | UIKit preset + blurAmount | intensity 1–100 |
| Android backend | RenderEffect | Dimezis BlurView | Dimezis BlurView |
| Android blur by default | ✅ (API 31+) | ✅ | ❌ opt-in |
| Cross-platform calibration | measured, 2.9% | not stated | manual |
| Liquid Glass | ✅ | ❌ | ❌ |
| Layer blur | ✅ | ❌ | ❌ |
| New Architecture | required | supported | supported |
The other two are good at what they set out to do, and neither claims the
platforms will match. expo-blur ships a blurReductionFactor documented as a
way to "fine tune it on Android to match it more closely with iOS" — an honest
description of a real situation, and it names the cost: agreement is your job, by
hand.
Reasons to pick something else — old architecture, Android below 12, a managed Expo workflow, or a review process that forbids private iOS symbols. All covered in the full comparison.
Size
| | | |---|---| | npm package | 46.6 kB packed · 167 kB unpacked | | JS bundle | +6.9 kB raw · +1.8 kB gzipped | | Runtime dependencies | none |
Measured as a real diff between two Metro release bundles. Details and the per-frame cost model are in performance and size.
Performance
Both platforms are GPU-only: no bitmap capture, no readback, no CPU blur, and no per-frame allocation.
iOS samples the backdrop through CABackdropLayer — the compositor reading
the frame it is already assembling — so there is no snapshot and no display link,
and scrolling costs nothing extra. Android re-records the views painted
before the blur into a RenderNode and hangs a RenderEffect off it.
The one counter-intuitive thing worth knowing: on Android the per-frame cost
scales with the number of views behind the blur, not with the blur's radius
or pixel area. The blur itself runs on a downscaled copy, so blurRadius={200}
costs about what blurRadius={20} costs. A simplified backdrop beats a smaller
radius every time.
Lists. Measured on a real device with ten blurred rows: a blur on every row
is 20.8% janky, while one blur over the whole list is 0.62% — as smooth as no
blur at all, despite overlapping every row. The GPU sits at 5–6 ms either way, so
the cost is per blur view, not per blurred pixel. Put the blur on the chrome
over the list, or use blurRadius={0} with a tintColor for cells. The
example's bench screen is an A/B rig; npm run bench:android measures it.
Performance and size has the cost model, the list guidance, and how to measure on your own hardware.
API
<FigmaBlurView />
| Prop | Type | Default | |
|---|---|---|---|
| blurRadius | number | 0 | Figma units — paste from the inspector |
| blurMode | 'backdrop' \| 'layer' | 'backdrop' | Figma's Background blur vs Layer blur |
| tintColor | ColorValue | — | Overlay fill above the blur |
| saturation | number | 1.0 | 1.0 is Figma-neutral; iOS materials ship ~1.8 |
| downsampleFactor | number | 0 | 0 picks from the radius |
| noiseOpacity | number | 0 | Grain, to dither banding on large flat blurs |
| glass | 'none' \| 'regular' \| 'clear' | 'none' | |
| glassTintColor | ColorValue | — | |
| glassInteractive | boolean | false | iOS 26+ only |
| fallbackColor | ColorValue | — | Painted where no GPU blur exists |
| enabled | boolean | true | Switch the blur off without unmounting |
Corner radii come from style — borderRadius and the per-corner variants — and
are applied to the blur's own mask.
<GlassView />
FigmaBlurView with glass preset and a matching default radius. Takes
variant ('regular' | 'clear').
Materials
ultraThin · thin · regular · thick, plus …Dark variants.
getCapabilities()
Reports which backend is live, whether the radius is exact, and whether glass is native or synthesised. Worth including in bug reports.
{ hasBackdropBlur, hasExactRadius, hasNativeGlass, hasShaderGlass, engine, apiLevel }Platform support
| | Backdrop blur | Exact radius | Glass |
|---|---|---|---|
| iOS 26+ | ✅ | ✅ | ✅ native |
| iOS 15.1–25 | ✅ | ✅ | ⚠️ synthesised |
| Android 13+ (33) | ✅ | ✅ | ⚠️ synthesised |
| Android 12 (31–32) | ✅ | ✅ | ⚠️ blur + tint only |
| Android < 12 | ❌ fallbackColor | — | ❌ |
Why Android 12 is the floor. Below API 31 there is no GPU backdrop blur on
Android at all — only CPU bitmap blurring, which drops frames on exactly the
low-end devices it would exist to serve. Rather than pretend, the library paints
fallbackColor. The package still installs at minSdk 24.
App Store note
The exact-radius path on iOS uses two private classes, CABackdropLayer and
CAFilter. They are used openly here — plain string literals, no obfuscation —
because you should be able to see exactly what is touched and decide for
yourself. They are the only way to set a real Gaussian radius on iOS.
Every lookup is nil-checked and every path degrades: if the classes are
unavailable the engine falls back to UIVisualEffectView, then to a fitted
intensity curve. A softer blur, never a crash.
getCapabilities().hasExactRadius tells you at runtime which one you got.
A build-time switch to remove the private symbols entirely is on the roadmap.
Documentation
- How it works — the sigma model, and what each platform actually does
- Verifying parity — the harness, the measured numbers, and two ways measuring has already gone wrong
- Troubleshooting — start with
getCapabilities() - Comparison — versus the alternatives, from their source
- Performance and size — what a blur costs per frame, and how to measure it on your own hardware
- Roadmap — what is next, and what is honestly not there yet
Running the example
git clone https://github.com/RaoMK/react-native-figma-blur
cd react-native-figma-blur
npm install && npm run prepare
cd example && npm install
cd ios && pod install && cd ..
npm run ios # or: npm run androidFour screens, switchable from the picker: gallery and scale are the plates above; parity is the measurement fixture — deliberately harsh, because a soft backdrop hides a wrong sigma; bench is the list A/B rig.
Contributing
Very welcome — see CONTRIBUTING.md. There is one rule that matters: a change to how a blur looks needs a measurement, not a screenshot. During development a blur shipped at 5× too weak and another at 48% too strong, and both looked entirely plausible by eye.
License
MIT © RaoMK
