react-native-ios-visual-effect-view

A small library to use UIVisualEffectView in react-native.

VisualEffectCustomFilterViewTest01Screen

VisualEffectCustomFilterViewTest01Screen

🚧⚠️ Work in Progress ⚠️🚧

This library + documentation is currently not finished yet. For now, please browse through examples directory to get a rough idea on how to use this library. Jump to basic usage section for example code + gif.

Acknowledgements

very special thanks to: junzhengca, brentvatne, expo, EvanBacon, corasan, lauridskern, ronintechnologies, and gerzonc for becoming a monthly sponsor, and thank you fobos531 for being a one time sponsor 🥺 (if you have the means to do so, please considering sponsoring here)

A. Introduction

2024-09-20-07-54-38.mp4

render-03.-.2024-12-18-14-01-19.-.re-encoded.mp4

• ❤️ Support for using UIVisualEffectView + all the system UIBlurEffectStyles.
• 🧡 Support for using custom blur radius and effect intensity (percent).
• 💚 Support for animating the blur effect style + blur radius changes.
• 💙 Support for creating and using filters (WIP)
• 💜 Runs on the old + new architecture (paper + fabric).

Testflight and Testing

The example app builds are automatically created and submitted on every version release via Xcode cloud, so if you just want to quickly try things out, the example app is available to try out via testflight (invite link).

Alternatively, you can also try out the corresponding example app to the native dependency that this library uses under the hood: VisualEffectBlurView (invite link).

Other Related Gifs

Experiment02ViewController.swift

VisualEffectBlurTestViewController.swift

VisualEffectViewExperiment01ViewController.swift

VisualEffectCustomFilterViewTest02Controller.swift

B. Installation

Note: Support for the new architecture (fabric), and backwards compatibility for the old architecture (paper) is handled via a peer dependency to react-native-ios-utilites@v5.

# 1. install library + dependencies
npm install react-native-ios-visual-effect-view@next
npm install react-native-ios-utilities@next

# 2. then run pod install (uses auto-linking)
cd ios && pod install

Updating

This library has cocoapods dependency to VisualEffectBlurView and DGSwiftUtilities, so you may need to update them separately (as needed).

# A. Either update this specific pod...
pod update VisualEffectBlurView DGSwiftUtilities
pod install --repo-update

# B. Or update all the pods
pod update

C. Basic Usage

hello! please see BlurViewBasicUsage01 for the full example

// 📝 Note: for the sake of brevity, some of the code is omitted...
import { BlurView } from 'react-native-ios-visual-effect-view';


export function BlurViewBasicUsage01() {
  return (
    <View style={styles.container}>
      <Text style={styles.label}>
        {'❤️\n🧡\n💛\n💚\n💙\n💜\n💖\n💃\n✨'}
      </Text>
      <RNIBlurView
        style={styles.effectOverlay}
        blurMode={{
          mode: 'blurEffectSystem',
          blurEffectStyle: 'prominent',
        }}
        animationConfig={{
          duration: 1,
          mode: 'presetCurve',
          curve: 'easeOut',
        }}
        animationDelay={1}
      />
    </View>
  );
}

D. Documentation

TBA

E. Examples

Please see the examples directory for the full list of examples, demos and tests.

CustomFilterViewExample01

Summary: Create a custom filter that darkens the views in the background, and applies a variable blur.

Notes
1️⃣ — The CustomFilterView.currentFilters prop accepts a CustomFilterConfig object; this object is used create and configure the underlying UIVisualEffectView effects. The CustomFilterConfig is comprised of several properties, but for this example we will be focusing on the CustomFilterConfig.backgroundFilters property (since it's required).
2️⃣ — The CustomFilterConfig.backgroundFilters property accepts an array of LayerFilterConfig object; the "filter entries" in this array defines what filters to use for the UIVisualEffectView's backdrop layer. The backdrop layer is special in that it is able to composite views that are behind it, and apply filters to it. 📝 Note: The "quality" of the composited views can be controlled via the CustomFilterView.backgroundLayerSamplingSizeScale prop; Setting this to 2.0 increases the sampling size, but at the cost of performance (use with caution).
3️⃣ — The LayerFilterConfig object is an tagged union type, with the LayerFilterConfig.filterName property being the "discriminant" that separates all the possible combinations. The filterName defines what type of filter to use; different types of filters have different inputs to control the look/behavior of the desired effect. In the example below, we define 4 LayerFilterConfig entries in the array for the CustomFilterConfig.backgroundFilters property: variadicBlur (variable blur), colorBlackAndWhite (color monochrome), brightenColors (color brightness), and contrastColors (color contrast). 📝 Note: The names for the filter are a bit weird because we can't use the internal filters directly. Please see LayerFilterTypeName.swift for the implementation details.

🔗 Full Example

export function CustomFilterViewExample01() {
  return (
    <View style={styles.container}>
      <Text style={styles.label}>
        {emojiString}
      </Text>
      <CustomFilterView
        style={styles.effectOverlay}
        // increase quality (usually: 0.25...1)
        backgroundLayerSamplingSizeScale={2}

        // set the filters to use,
        // accepts an array of `LayerFilterConfig`
        currentFilters={{
          backgroundFilters: [
            // filter 1 of 4
            // create variable blur filter
            {
              filterName: 'variadicBlur',
              radius: 8,
              shouldNormalizeEdges: true,

              // define the intensity of blur via a gradient
              gradientMask: {
                type: 'axial',
                colors: [
                  'rgba(0,0,0,1)', // max blur
                  'rgba(0,0,0,0)', // no blur
                ],
                startPointPreset: 'topCenter',
                endPointPreset: 'bottomCenter',
                size: {
                  height: WINDOW_SIZE.height,
                  width: WINDOW_SIZE.width,
                },
              }
            },

            // filter 2 of 4
            // Slightly desaturate colors
            {
              filterName: 'colorBlackAndWhite',
              amount: 0.5
            },

            // filter 3 of 4
            // reduce brightness
            {
              filterName: 'brightenColors',
              amount: -0.5
            },

            // filter 4 of 4
            // decrease contrast
            {
              filterName: 'contrastColors',
              amount: 0.4,
            },
          ]
        }}
      >
        <Text>
          {'Hello World'}
        </Text>
      </CustomFilterView>
    </View>
  );
}

CustomFilterViewExample02

Summary: TBA

🔗 Full Example

export function CustomFilterViewExample02() {
  // ...
  return (
    <View style={styles.container}>
      { /* ... */ }
      <CustomFilterView
        style={styles.effectOverlay}
        backgroundLayerSamplingSizeScale={2}
        currentFilters={{
          backgroundFilters: [
            {
              filterName: 'gaussianBlur',
              radius: 18,
              shouldNormalizeEdges: true,
            },
            {
              filterName: 'brightenColors',
              amount: -0.5
            },
            {
              filterName: 'contrastColors',
              amount: 0.3,
            },
            {
              filterName: 'colorBlackAndWhite',
              amount: 1,
            },
          ],
          tintConfig: {
            opacity: 0.75,
            blendMode: 'color',
            tintColor: 'red',
          },
          foregroundFilters: [
            {
              filterName: 'gaussianBlur',
              radius: 4,
              shouldNormalizeEdges: false
            },
            {
              filterName: 'colorMatrixVibrant',
              colorMatrix: {
                mode: 'preset',
                preset: {
                  mode: 'presetName',
                  presetName: 'preset14'
                },
              },
            },
          ]
        }}
      >
        <View style={styles.effectContent}>
          <CounterDisplay
            counter={counter}
          />
        </View>
      </CustomFilterView>
    </View>
  );
}

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library