|
| 1 | +--- |
| 2 | +keywords: |
| 3 | + [ |
| 4 | + react-native-keyboard-controller, |
| 5 | + KeyboardAvoidingView, |
| 6 | + keyboard avoiding view, |
| 7 | + avoid keyboard, |
| 8 | + android, |
| 9 | + ] |
| 10 | +--- |
| 11 | + |
| 12 | +# KeyboardAvoidingView |
| 13 | + |
| 14 | +This component will automatically adjust its height, position, or bottom padding based on the keyboard height to remain visible while the virtual keyboard is displayed. |
| 15 | + |
| 16 | +## Why another `KeyboardAvoidingView` is needed? |
| 17 | + |
| 18 | +This new `KeyboardAvoidingView` maintains the familiar React Native [API](https://reactnative.dev/docs/keyboardavoidingview) but ensures consistent behavior and animations on both `iOS` and `Android` platforms. Unlike the existing solution, which primarily caters to `iOS`, this component eliminates platform discrepancies, providing a unified user experience. By reproducing the same animations and behaviors on both platforms, it simplifies cross-platform development, meets user expectations for consistency, and enhances code maintainability. Ultimately, it addresses the need for a reliable and uniform keyboard interaction solution across different devices. |
| 19 | + |
| 20 | +Below is a visual difference between the implementations (the animation is _**4x**_ times slower for better visual perception). |
| 21 | + |
| 22 | +import KeyboardAvoidingViewComparison from "@site/src/components/KeyboardAvoidingViewComparison"; |
| 23 | + |
| 24 | +<KeyboardAvoidingViewComparison /> |
| 25 | + |
| 26 | +:::info Found a bug? Help the project and report it! |
| 27 | + |
| 28 | +If you found any bugs or inconsistent behavior comparing to `react-native` implementation - don't hesitate to open an [issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new?assignees=kirillzyusko&labels=bug&template=bug_report.md&title=). It will help the project 🙏 |
| 29 | + |
| 30 | +Also if there is any well-known problems in original `react-native` implementation which can not be fixed for a long time and they are present in this implementation as well - also feel free to submit an [issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new?assignees=kirillzyusko&labels=bug&template=bug_report.md&title=). Let's make this world better together 😎 |
| 31 | + |
| 32 | +::: |
| 33 | + |
| 34 | +## Example |
| 35 | + |
| 36 | +```tsx |
| 37 | +import React from "react"; |
| 38 | +import { |
| 39 | + Text, |
| 40 | + TextInput, |
| 41 | + TouchableOpacity, |
| 42 | + View, |
| 43 | + StyleSheet, |
| 44 | +} from "react-native"; |
| 45 | +import { KeyboardAvoidingView } from "react-native-keyboard-controller"; |
| 46 | + |
| 47 | +export default function KeyboardAvoidingViewExample() { |
| 48 | + return ( |
| 49 | + <KeyboardAvoidingView |
| 50 | + behavior={"padding"} |
| 51 | + keyboardVerticalOffset={100} |
| 52 | + style={styles.content} |
| 53 | + > |
| 54 | + <View style={styles.inner}> |
| 55 | + <Text style={styles.heading}>Header</Text> |
| 56 | + <View> |
| 57 | + <TextInput placeholder="Username" style={styles.textInput} /> |
| 58 | + <TextInput placeholder="Password" style={styles.textInput} /> |
| 59 | + </View> |
| 60 | + <TouchableOpacity style={styles.button}> |
| 61 | + <Text style={styles.text}>Submit</Text> |
| 62 | + </TouchableOpacity> |
| 63 | + </View> |
| 64 | + </KeyboardAvoidingView> |
| 65 | + ); |
| 66 | +} |
| 67 | + |
| 68 | +const styles = StyleSheet.create({ |
| 69 | + content: { |
| 70 | + flex: 1, |
| 71 | + maxHeight: 600, |
| 72 | + }, |
| 73 | + heading: { |
| 74 | + fontSize: 36, |
| 75 | + marginBottom: 48, |
| 76 | + fontWeight: "600", |
| 77 | + }, |
| 78 | + inner: { |
| 79 | + padding: 24, |
| 80 | + flex: 1, |
| 81 | + justifyContent: "space-between", |
| 82 | + }, |
| 83 | + textInput: { |
| 84 | + height: 45, |
| 85 | + borderColor: "#000000", |
| 86 | + borderWidth: 1, |
| 87 | + borderRadius: 10, |
| 88 | + marginBottom: 36, |
| 89 | + paddingLeft: 10, |
| 90 | + }, |
| 91 | + button: { |
| 92 | + marginTop: 12, |
| 93 | + height: 45, |
| 94 | + borderRadius: 10, |
| 95 | + backgroundColor: "rgb(40, 64, 147)", |
| 96 | + justifyContent: "center", |
| 97 | + alignItems: "center", |
| 98 | + }, |
| 99 | + text: { |
| 100 | + fontWeight: "500", |
| 101 | + fontSize: 16, |
| 102 | + color: "white", |
| 103 | + }, |
| 104 | +}); |
| 105 | +``` |
| 106 | + |
| 107 | +## Props |
| 108 | + |
| 109 | +### [`View Props`](https://reactnative.dev/docs/view#props) |
| 110 | + |
| 111 | +Inherits [View Props](https://reactnative.dev/docs/view#props). |
| 112 | + |
| 113 | +### `behavior` |
| 114 | + |
| 115 | +Specify how to react to the presence of the keyboard. Could be one value of: |
| 116 | + |
| 117 | +- `translate-with-padding` - Combines **translation** (moves the view up) with **paddingTop** that gets applied only once per animation. As a result this mode delivers **the best** possible performance. An ideal fit for building **chat-like** apps. |
| 118 | + |
| 119 | +- `padding` - the most commonly used mode. It moves the view up by the height of the keyboard and applies `paddingBottom` to the content container. Use `padding` mode when you have a `ScrollView` or `flex-based` layouts that should remain visible. |
| 120 | + |
| 121 | +- `height` - use this when you want to shrink the entire view rather than moving specific elements. |
| 122 | + |
| 123 | +- `position` - use it when the view needs to shift up instead of resizing. For example when you have a fixed button at the bottom (also be sure that you checked out [KeyboardStickyView](./keyboard-sticky-view) component). |
| 124 | + |
| 125 | +### `contentContainerStyle` |
| 126 | + |
| 127 | +The style of the content container (View) when behavior is `position`. |
| 128 | + |
| 129 | +### `enabled` |
| 130 | + |
| 131 | +A boolean prop indicating whether `KeyboardAvoidingView` is enabled or disabled. Default is `true`. |
| 132 | + |
| 133 | +### `keyboardVerticalOffset` |
| 134 | + |
| 135 | +This is the distance between the top of the user screen and the react native view. This is particularly useful when there are fixed headers, navigation bars, or other UI elements at the top of the screen. Default is `0`. |
| 136 | + |
| 137 | +import KeyboardVerticalOffset from "@site/src/components/KeyboardVerticalOffset"; |
| 138 | + |
| 139 | +<details> |
| 140 | + <summary>When to use `keyboardVerticalOffset`?</summary> |
| 141 | + |
| 142 | +You should use `keyboardVerticalOffset` in the following scenarios: |
| 143 | + |
| 144 | +- **Navigation Bars / Headers** - If your screen is inside a `Stack.Navigator` from `react-navigation`, the header height should be compensated using `keyboardVerticalOffset`: |
| 145 | + |
| 146 | +```tsx |
| 147 | +import { useHeaderHeight } from "@react-navigation/elements"; |
| 148 | +import { KeyboardAvoidingView } from "react-native-keyboard-controller"; |
| 149 | + |
| 150 | +const MyScreen = () => { |
| 151 | + const headerHeight = useHeaderHeight(); |
| 152 | + |
| 153 | + return ( |
| 154 | + <KeyboardAvoidingView |
| 155 | + behavior="padding" |
| 156 | + keyboardVerticalOffset={headerHeight} |
| 157 | + > |
| 158 | + <TextInput placeholder="Type here..." /> |
| 159 | + </KeyboardAvoidingView> |
| 160 | + ); |
| 161 | +}; |
| 162 | +``` |
| 163 | + |
| 164 | +- **Custom Toolbars or Fixed Elements at the Top** - If your app has a fixed toolbar, status bar, or other UI elements at the top, you should offset accordingly. |
| 165 | + |
| 166 | +- **Modal Screens with Different Layouts** - When using `KeyboardAvoidingView` inside a `Modal`, you may need to manually define the vertical offset to account for the modal’s positioning. |
| 167 | + |
| 168 | +Below shown a visual representation of `keyboardVerticalOffset`: |
| 169 | + |
| 170 | +<KeyboardVerticalOffset /> |
| 171 | + |
| 172 | +:::warning Handling `StatusBar` height on Android with `useHeaderHeight` |
| 173 | +On `Android`, how you handle the `StatusBar` height depends on whether the `StatusBar` is **translucent** or **not**: |
| 174 | + |
| 175 | +- **If the `StatusBar` is translucent**, `react-navigation` **automatically includes the `StatusBar` height** in `useHeaderHeight()`, along with safe-area padding. This behavior aligns with iOS, so you don’t need to manually add the `StatusBar` height. |
| 176 | +- **If the StatusBar is not translucent**, `useHeaderHeight()` does **not** include the `StatusBar` height. In this case, you need to add it manually: |
| 177 | + |
| 178 | +```tsx |
| 179 | +const headerHeight = useHeaderHeight() + (StatusBar.currentHeight ?? 0); |
| 180 | +``` |
| 181 | + |
| 182 | +Since `StatusBar.currentHeight` is an **Android-only** property, using `?? 0` ensures it doesn’t cause issues on iOS. This approach avoids the need for `Platform.OS` or `Platform.select` checks. |
| 183 | + |
| 184 | +::: |
| 185 | + |
| 186 | +</details> |
0 commit comments