DOCSEARCHbyAlgolia
Submit Docs

react-native-blur

repository·main·Indexed 43 days ago

https://github.com/sbaiahmed1/react-native-blur

A high-performance React Native library providing native blur, vibrancy, and liquid-glass effects for iOS, Android, and Web. Optimized for the New Architecture (Fabric), it requires React Native 0.80+ and includes specialized components such as BlurView, ProgressiveBlurView, VibrancyView, LiquidGlassView, LiquidGlassContainer, and BlurSwitch. Version 6.0.1.

Tokens
14.6K
Snippets
48
Records
79
Agent score
52%

What's inside react-native-blur

  1. Overview of @sbaiahmed1/react-native-blur

    main

    This library provides native blur, vibrancy, and iOS 26 liquid-glass effects for React Native across iOS, Android, and Web. It is built specifically for the React Native New Architecture (Fabric) and provides six specialized components:

    • BlurView: Standard blur effect.
    • ProgressiveBlurView: Progressive/gradient blur.
    • VibrancyView: Vibrancy effects.
    • LiquidGlassView: Liquid glass effects.
    • LiquidGlassContainer: Container for liquid glass effects.
    • BlurSwitch: A blurred switch component.

  2. Android backend implementation notes

    main

    The Android implementation captures the surrounding view tree (scoped to the nearest react-native-screens Screen, or the React root) into a downsampled bitmap to perform the blur. Keep these two consequences in mind:

    1. Performance: Both capturing the view and performing the blur iterations are computationally expensive. You can trade quality for performance by adjusting settings, but you should measure on target devices to identify if capture or blur is the bottleneck.
    2. Foreground Content: Because Android captures the surrounding view tree, other foreground siblings inside the capture root may appear blurred. To prevent this, move those siblings outside the capture root (for example, using a Portal above the navigator). Note that the ProgressiveBlurView children are excluded from the capture and render sharp above the blur.

  3. Understand the Astro project structure

    main

    Astro projects follow a specific directory structure for routing and assets:

    • src/pages/: Contains .astro or .md files. Each file in this directory is exposed as a route based on its filename.
    • src/components/: A recommended location for storing Astro, React, Vue, Svelte, or Preact components.
    • public/: A directory for static assets like images that should be served as-is.
    • package.json: Defines project dependencies and scripts.
    /
├── public/
├── src/
│   └── pages/
│       └── index.astro
└── package.json

  4. Configure colors for BlurSwitch on Android vs iOS/Web

    main

    Color configuration for BlurSwitch depends on the target platform:

    Android

    On Android, the track is blurred. You should only provide the base color for the 'on' state using trackColor.true. The QmBlurView engine automatically derives the 'off' state shade from this color.

    Note: thumbColor and trackColor.false are ignored on Android.

    iOS and Web

    On these platforms, the component behaves like a standard React Native Switch. You can use thumbColor and trackColor.false to define specific colors for the thumb and the track in its off-state.

    // Android: Only trackColor.true is used for the blur calculation
<BlurSwitch
  value={isEnabled}
  onValueChange={setIsEnabled}
  blurAmount={15}
  trackColor={{ true: '#8B5CF6' }}
/>

// iOS/Web: Standard Switch colors apply
<BlurSwitch
  value={isEnabled}
  onValueChange={setIsEnabled}
  trackColor={{ true: '#8B5CF6', false: '#D1D1D6' }}
  thumbColor="#FFFFFF"
/>

  5. Understand Web behavior for BlurView

    main

    On react-native-web, BlurView implements blur using CSS:

    • Implementation: It renders a backdrop-filter: blur() saturate(180%) layer combined with a semi-transparent background tint derived from the blurType.
    • Blur Intensity: The blurAmount prop (0-100) scales directly to the CSS blur radius.
    • Layering: Children render above the blur layer and remain sharp.
    • Graceful Degradation: In browsers that do not support backdrop-filter (or during SSR), only the semi-transparent tint is rendered.
    • Platform Differences: The following props are no-ops on Web: blurRounds, reducedTransparencyFallbackColor, and ignoreSafeArea.
    • Refs: A forwarded ref resolves to the root View (a DOM element).

  6. Use LiquidGlassContainer to group glass elements

    main

    The LiquidGlassContainer component wraps iOS 26+'s UIGlassContainerEffect. It is used to group multiple LiquidGlassView children together, applying a merge/blend effect between nearby glass shapes.

    Platform Behavior:

    • iOS 26+: Enables the native merge/blend effect between children with configurable spacing.
    • Android 13+: Each LiquidGlassView child renders native liquid glass individually, but the container's merge/blend effect is not applied.
    • Android (below 13), Web, and iOS (< 26): Falls back to a plain View. In these cases, the spacing prop has no effect.
    import { LiquidGlassContainer, LiquidGlassView } from '@sbaiahmed1/react-native-blur';

<LiquidGlassContainer spacing={20} style={{ flex: 1 }}>
  <LiquidGlassView
    glassType="clear"
    glassTintColor="#000000"
    glassOpacity={0.3}
    style={{ width: 120, height: 120, borderRadius: 60 }}
  >
    <Text>Circle 1</Text>
  </LiquidGlassView>
  <LiquidGlassView
    glassType="clear"
    glassTintColor="#000000"
    glassOpacity={0.3}
    style={{ width: 120, height: 120, borderRadius: 60 }}
  >
    <Text>Circle 2</Text>
  </LiquidGlassView>
</LiquidGlassContainer>

  7. Understand ProgressiveBlurView platform differences and startOffset

    main

    While ProgressiveBlurView aims for a consistent look across platforms, the underlying implementation of the blur ramp differs:

    • Blur Ramp: iOS and Web ramp the blur radius from blurAmount down to 0. Android renders one fixed-radius blur and ramps its opacity using an eased mask.
    • startOffset Behavior: Since version 6.0, startOffset behaves consistently across all platforms:
      • Edge Directions (e.g., blurredTopClearBottom): It defines a fully-blurred plateau at the specified edge. For example, 0.4 means the nearest 40% of the view is uniformly blurred, and the fade spans the remaining 60%.
      • Center Direction (blurredCenterClearTopAndBottom): It insets the fade start from the edges (clamped to 0.3), effectively shortening the blur body. 0 results in the longest blur body.

    Note for users migrating from < 6.0: Previously, iOS interpreted startOffset inversely for edge directions. If you were using Platform.select to tune offsets, you should now use a single value and verify the fade geometry.

  8. Understand Android behavior and performance for BlurView

    main

    Android uses QmBlurView, which works by capturing the surrounding view tree (scoped to the nearest react-native-screens Screen, or falling back to the React root) into a downsampled bitmap and blurring it.

    Performance Considerations

    Both the capture and the blur process consume resources:

    • Capture: Uses a downsampled bitmap.
    • Blur: Each blurRounds iteration adds a native blur pass. To improve performance, lower the blurRounds value, though this may reduce quality.

    The 'Blurred Halo' Effect

    On Android, the capture process includes anything rendered above the blur within the capture root. This can result in a 'blurred halo' appearing under the crisp original content.

    Solution: If you see a halo effect, move the content that should remain sharp outside of the capture root (for example, using a Portal above the navigator).

  9. Install @sbaiahmed1/react-native-blur

    main

    Install the package using yarn and then install the iOS dependencies using CocoaPods.

    Note: This library requires React Native 0.80+ with the New Architecture enabled.

    yarn add @sbaiahmed1/react-native-blur
# then, for iOS:
cd ios && pod install

  10. Requirements for @sbaiahmed1/react-native-blur

    main

    Before installing, ensure your environment meets the following minimum requirements. Note that this library only supports the React Native New Architecture (Fabric) and does not support the legacy Paper architecture.

    PlatformMinimum versionNotes
    iOS13.0+Xcode 16+ required; Xcode 26.0+ for Liquid Glass
    AndroidAPI 24+ (Android 7.0)Android Gradle Plugin 8.9.1+ required
    Webreact-native-webRequires CSS backdrop-filter support
    React Native0.80+New Architecture must be enabled

    Liquid Glass Support

    • iOS: Requires Xcode 26.0+ and iOS 26+ for the full glass effect and LiquidGlassContainer's merge effect. On older versions, it falls back to an enhanced blur approximation.
    • Android: Requires Android 13+ (API 33) for AGSL RuntimeShader support. On older versions, it falls back to an enhanced blur approximation.