chore: update README.md (#494)
This commit is contained in:
André Ribeiro
GitHub
parent
7c49acf896
commit
24b456b649
179
README.md
179
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 (
|
||||
<View style={styles.container}>
|
||||
<Image
|
||||
key={'blurryImage'}
|
||||
source={{ uri }}
|
||||
style={styles.absolute}
|
||||
/>
|
||||
<Text style={styles.absolute}>Hi, I am some blurred text</Text>
|
||||
{/* in terms of positioning and zIndex-ing everything before the BlurView will be blurred */}
|
||||
<BlurView
|
||||
style={styles.absolute}
|
||||
blurType="light"
|
||||
blurAmount={10}
|
||||
reducedTransparencyFallbackColor="white"
|
||||
/>
|
||||
<Text>I'm the non blurred text because I got rendered on top of the BlurView</Text>
|
||||
</View>
|
||||
);
|
||||
}
|
||||
export default function Menu() {
|
||||
return (
|
||||
<View style={styles.container}>
|
||||
<Image
|
||||
key={'blurryImage'}
|
||||
source={{ uri }}
|
||||
style={styles.absolute}
|
||||
/>
|
||||
<Text style={styles.absolute}>Hi, I am some blurred text</Text>
|
||||
{/* in terms of positioning and zIndex-ing everything before the BlurView will be blurred */}
|
||||
<BlurView
|
||||
style={styles.absolute}
|
||||
blurType="light"
|
||||
blurAmount={10}
|
||||
reducedTransparencyFallbackColor="white"
|
||||
/>
|
||||
<Text>I'm the non blurred text because I got rendered on top of the BlurView</Text>
|
||||
</View>
|
||||
)
|
||||
}
|
||||
|
||||
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 (
|
||||
<Image source={{ uri }} style={styles.absolute}>
|
||||
<VibrancyView blurType="light" style={styles.flex}>
|
||||
<Text>Hi, I am some vibrant text.</Text>
|
||||
</VibrancyView>
|
||||
</Image>
|
||||
);
|
||||
}
|
||||
export default function Menu() {
|
||||
return (
|
||||
<Image source={{ uri }} style={styles.absolute}>
|
||||
<VibrancyView blurType="light" style={styles.flex}>
|
||||
<Text>Hi, I am some vibrant text.</Text>
|
||||
</VibrancyView>
|
||||
</Image>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue