diff --git a/README.md b/README.md index 063ac5f..610001b 100644 --- a/README.md +++ b/README.md @@ -12,106 +12,94 @@ A component for UIVisualEffectView's blur and vibrancy effect on iOS, and [BlurV ### Content - [Installation](#installation) -- [BlurView](#blurview) +- [Usage](#usage) - [VibrancyView](#vibrancyview) - [Example React Native app](#example-react-native-app) - [Questions?](#questions) ### Installation -1. Install the library using either Yarn: - ``` yarn add @react-native-community/blur ``` -or npm: +Install native dependencies (iOS only): -``` -npm install --save @react-native-community/blur -``` - -2. (iOS only) Install native dependencies: - -``` -npx pod-install -``` -Or, if you already have installed [Cocoapods](https://cocoapods.org/) on your system: ``` cd ios && pod install ``` -3. Include the library in your code: +### Usage -```javascript -import { BlurView, VibrancyView } from "@react-native-community/blur"; -``` +#### BlurView -4. Build and have fun! +| Property | Possible Values | Default | Platform +| ----------- | ----------- | ----------- | ----------- +| `blurType` | See blurType below | - | All +| `blurAmount` | 0 - 100 (The maximum blurAmount on Android is 32, so higher values will be clamped to 32) | 10 | All +| `reducedTransparencyFallbackColor` | Any color | - | iOS only +| `blurRadius` | 0 - 25 | Matches iOS blurAmount | Android only +| `downsampleFactor` | 0 - 25 | Matches iOS blurAmount | Android only +| `overlayColor` | Any color | Default color based on iOS blurType | Android only -### BlurView +#### blurType -**Properties:** +| Name | Description +| ----------- | ----------- +| `xlight` | extra light blur type +| `light` | light blur type +| `dark` | dark blur type +| `extraDark` | extra dark blur type (tvOS only) +| `regular` | regular blur type (iOS 10+ and tvOS only) +| `prominent` | prominent blur type (iOS 10+ and tvOS only) -- `blurType` (String) - - `xlight` - extra light blur type - - `light` - light blur type - - `dark` - dark blur type - - `extraDark` - extra dark blur type (tvOS only) - - `regular` - regular blur type (iOS 10+ and tvOS only) - - `prominent` - prominent blur type (iOS 10+ and tvOS only) - - iOS 13 only Blur types: - - `chromeMaterial` - An adaptable blur effect that creates the appearance of the system chrome. - - `material` - An adaptable blur effect that creates the appearance of a material with normal thickness. - - `thickMaterial` - An adaptable blur effect that creates the appearance of a material that is thicker than normal. - - `thinMaterial` - An adaptable blur effect that creates the appearance of an ultra-thin material. - - `ultraThinMaterial` - An adaptable blur effect that creates the appearance of an ultra-thin material. - - `chromeMaterialDark` - A blur effect that creates the appearance of an ultra-thin material and is always dark. - - `materialDark` - A blur effect that creates the appearance of a thin material and is always dark. - - `thickMaterialDark` - A blur effect that creates the appearance of a material with normal thickness and is always dark. - - `thinMaterialDark` - A blur effect that creates the appearance of a material that is thicker than normal and is always dark. - - `ultraThinMaterialDark` - A blur effect that creates the appearance of the system chrome and is always dark. - - `chromeMaterialLight` - An adaptable blur effect that creates the appearance of the system chrome. - - `materialLight` - An adaptable blur effect that creates the appearance of a material with normal thickness. - - `thickMaterialLight` - An adaptable blur effect that creates the appearance of a material that is thicker than normal. - - `thinMaterialLight` - An adaptable blur effect that creates the appearance of a thin material. - - `ultraThinMaterialLight` - An adaptable blur effect that creates the appearance of an ultra-thin material. -- `blurAmount` (Default: 10, Number) - - `0-100` - Adjusts blur intensity -- `reducedTransparencyFallbackColor` (Color) (iOS only) - - `black, white, #rrggbb, etc` - background color to use if accessibility setting ReduceTransparency is enabled +#### blurType (iOS 13 only) -> Note: The maximum `blurAmount` on Android is 32, so higher values will be clamped to 32. +| Name | Description +| ----------- | ----------- +| `chromeMaterial` | An adaptable blur effect that creates the appearance of the system chrome. +| `material` | An adaptable blur effect that creates the appearance of a material with normal thickness. +| `thickMaterial` | An adaptable blur effect that creates the appearance of a material that is thicker than normal. +| `chromeMaterial` | An adaptable blur effect that creates the appearance of the system chrome. +| `thinMaterial` | An adaptable blur effect that creates the appearance of an ultra-thin material. +| `ultraThinMaterial` | An adaptable blur effect that creates the appearance of an ultra-thin material. +| `chromeMaterialDark` | A blur effect that creates the appearance of an ultra-thin material and is always dark. +| `materialDark` | A blur effect that creates the appearance of a thin material and is always dark. +| `thickMaterialDark` | A blur effect that creates the appearance of a material with normal thickness and is always dark. +| `thinMaterialDark` | A blur effect that creates the appearance of a material that is thicker than normal and is always dark. +| `ultraThinMaterialDark` | A blur effect that creates the appearance of the system chrome and is always dark. +| `chromeMaterialLight` | An adaptable blur effect that creates the appearance of the system chrome. +| `materialLight` | An adaptable blur effect that creates the appearance of a material with normal thickness. +| `thickMaterialLight` | An adaptable blur effect that creates the appearance of a material that is thicker than normal. +| `thinMaterialLight` | An adaptable blur effect that creates the appearance of a thin material. +| `ultraThinMaterialLight` | An adaptable blur effect that creates the appearance of an ultra-thin material. -> Complete usage example that works on iOS and Android: +Complete usage example that works on iOS and Android: ```javascript import React, { Component } from "react"; import { View, Image, Text, StyleSheet } from "react-native"; import { BlurView } from "@react-native-community/blur"; -export default class Menu extends Component { - - render() { - return ( - - - Hi, I am some blurred text -{/* in terms of positioning and zIndex-ing everything before the BlurView will be blurred */} - - I'm the non blurred text because I got rendered on top of the BlurView - - ); - } +export default function Menu() { + return ( + + + Hi, I am some blurred text + {/* in terms of positioning and zIndex-ing everything before the BlurView will be blurred */} + + I'm the non blurred text because I got rendered on top of the BlurView + + ) } const styles = StyleSheet.create({ @@ -131,64 +119,47 @@ const styles = StyleSheet.create({ In this example, the `Image` component will be blurred, because the `BlurView` in positioned on top. But the `Text` will stay unblurred. -If the [accessibility setting `Reduce Transparency`](https://support.apple.com/guide/iphone/display-settings-iph3e2e1fb0/ios) is enabled the `BlurView` will use `reducedTransparencyFallbackColor` as it's background color rather than blurring. If no `reducedTransparencyFallbackColor` is provided, the`BlurView`will use the default fallback color (white, black, or grey depending on `blurType`) +If the accessibility setting [`Reduce Transparency`](https://support.apple.com/guide/iphone/display-settings-iph3e2e1fb0/ios) is enabled the `BlurView` will use `reducedTransparencyFallbackColor` as it's background color rather than blurring. If no `reducedTransparencyFallbackColor` is provided, the`BlurView`will use the default fallback color (white, black, or grey depending on `blurType`) ### VibrancyView -**Uses the same properties as `BlurView` (`blurType`, `blurAmount`, and `reducedTransparencyFallbackColor`).** +Uses the same properties as `BlurView` (`blurType`, `blurAmount`, and `reducedTransparencyFallbackColor`). -> The vibrancy effect lets the content underneath a blurred view show through more vibrantly +The vibrancy effect lets the content underneath a blurred view show through more vibrantly -> (Note: `VibrancyView` is only supported on iOS. Also note that the `VibrancyView` must contain nested views.) +`VibrancyView is only supported on iOS. Also note that the VibrancyView must contain nested views` ```javascript import { VibrancyView } from "@react-native-community/blur"; -export default class Menu extends Component { - render() { - return ( - - - Hi, I am some vibrant text. - - - ); - } +export default function Menu() { + return ( + + + Hi, I am some vibrant text. + + + ) } ``` -### Android - -Android uses the [BlurView](https://github.com/Dimezis/BlurView). - -If you only need to support iOS, then you can safely ignore these limitations. - -In addition to `blurType` and `blurAmount`, Android has some extra props that can be used to override the default behavior (or configure Android-specific behavior): - -- `blurRadius` (Number - between 0 and 25) - Manually adjust the blur radius. (Default: matches iOS blurAmount) -- `downsampleFactor` (Number - between 0 and 25) - Scales down the image before blurring (Default: matches iOS blurAmount) -- `overlayColor` (Color) - Set a custom overlay color (Default color based on iOS blurType) - ### Example React Native App This project includes an example React Native app, which was used to make the GIF in this README. You can run the apps by following these steps: -1. Clone the repository +Clone the repository ``` -cd ~ git clone https://github.com/react-native-community/react-native-blur.git ``` -2. Install dependencies +Install dependencies ``` yarn ``` -3. Run the apps: - #### Run the app ``` @@ -197,4 +168,4 @@ yarn example android/ios ### Questions? -Feel free to contact me on [twitter](https://twitter.com/kureevalexey) or [create an issue](https://github.com/Kureev/react-native-blur/issues/new) +Feel free to [create an issue](https://github.com/Kureev/react-native-blur/issues/new)