Getting Started

1. Installation & Requirements

This library follows the React Native releases support policy. It is supporting the latest version, and the two previous minor series. You may find it working correctly with some older React Native versions, but it'll be a "Use at your own risk" case.

This library supports "New Architecture".

Library supports Android & iOS, for out-of-tree platforms, View component is used as fallback.

Install library with your package manager:

yarn add react-native-avoid-softinput

or

npm i --save react-native-avoid-softinput

(iOS-only) Install pods:

npx pod-install

(iOS-only) Create and configure bridging header

Create and configure bridging header in your iOS project, if it doesn't exist (the easiest way is to create empty .swift file in XCode) - for reference, check out Apple's dedicated docs section.

Expo

• ✅ You can use this library with Development Builds. No config plugin is required.
• ❌ This library can't be used in the "Expo Go" app because it requires custom native code.

2. App's setup

Setting Kotlin version

The library uses Kotlin language to implement Android part. Depending on the version of React Native or Expo SDK and 3rd party libraries that are used in your project, you might (or might not) need to explicitly specify the version of Kotlin used in the app.

• Expo project after prebuild / bare RN project

Go to <projectDir>/android/build.gradle inside your android folder to specify your kotlinVersion

buildscript {
    ext {
        kotlinVersion = "1.7.22"  // <-- add a version here for resolution, version can be newer depending on the React Native version used in the project
    }
}

• Expo project before prebuild / Expo managed project

Use expo-build-properties plugin to modify kotlinVersion value

npx expo install expo-build-properties

Add plugin inside of your app.json or app.config.js

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "kotlinVersion": "1.7.22" // <-- add a version here for resolution, version can be newer depending on the Expo SDK version used in the project
          }
        }
      ]
    ]
  }
}

Keyboard handling on Android

To make the keyboard handled only by react-native-avoid-softinput (and not by Android OS), you have to additionally make sure that default keyboard handling on Android is switched off (for iOS nothing to be done 🚀). To do that, you need to make 2 steps:

Modify your Android's project AndroidManifest.xml

• Expo project after prebuild / bare RN project

Go to <projectDir>/android/app/src/main/AndroidManifest.xml and search for android:windowSoftInputMode attribute in the <activity> element. To make react-native-avoid-softinput responsible for managing the available space when keyboard is popped up, that attribute needs to be set to adjustResize (in a new RN project it should be the default).

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
      android:name=".MainApplication">
      <activity
        android:name=".MainActivity"
        android:windowSoftInputMode="adjustResize"
        android:launchMode="singleTask"
        android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
      </activity>
    </application>

</manifest>

• Expo project before prebuild / Expo managed project

Go to Expo's app.json/app.config.js and modify softwareKeyboardLayoutMode, so that it has resize value (in a new Expo project it should be the default).

Use AvoidSoftInput.setShouldMimicIOSBehavior(true) later on in your app's code

Remember to call AvoidSoftInput.setShouldMimicIOSBehavior(true) somewhere in the project's code (either in some root component, if you use the library globally or in specific screen, if you use the library only in some places).

3. Define your use case

There're many possible ways to implement a form with some text fields. Depending on the ideas of the UX team and the imagination of the client/product owner, you may need to implement some complex layouts, that not only have to be accessible, but should behave in a consistent way when the interaction with text fields/keyboard takes place.

Creating some generic components (like KeyboardAvoidingView) that can magically wrap any form layout in your app is an anti-pattern. Especially, when there are many variables that may change the expected behavior like:

• whether Android OS default keyboard handling is switched on or off
• whether the form layout is in the scrollable container or not
• are elements like modals/bottomsheets used and are these implemented in the JS layer or use some native primitives
• how complex those inputs are, how many text fields there are
• should some elements in the form be sticky
• etc.

Instead, you should think how the keyboard interaction with the app should look, what elements should be visible when the keyboard pops up.

In a basic case where you have a fullscreen scrollable form without a need to have submit button always visible, you might use AvoidSoftInput module which pushes the whole root view above the keyboard, or detects the nearest scrollable ancestor and tries to scroll to covered text field element.

In a more advanced case where you have a form inside a modal layout with text field inside, you may use AvoidSoftInputView component which pushes itself above the keyboard, or detects the nearest scrollable ancestor and tries to scroll to covered text field element.

In other case you have a task to make a form footer with submit buttons always visible even when the keyboard slides in (effectively making that footer sticky). Then, you have to think how to make that footer separated from the rest of the text fields that are probably in some scrollable container. At the end, you'll end up in a need to manually apply padding to the footer container. Luckily, you might try useSoftInputShown, useSoftInputHidden & useSoftInputHeightChanged hooks to detect when the keyboard is displayed and the height value it has.

The point is, before blindly using the library, you should define what is the expected behavior and which tools you should use to achieve it. If you don't know, which APIs from the library you should use for your use case, check the example app and try to play with available APIs.

Troubleshooting

Incorrect kotlinVersion

For more context, check GH issue 88.

Sometimes when using this library you may find that your build fails due to incorrect kotlinVersion in your native project. To catch this you need to follow Setting Kotlin version section.

Doubled padding on Android when form has many inputs, works as expected on iOS

For more context, check GH issue 155.

The problem may appear if you didn't follow Keyboard handling on Android section and you have e.g. adjustPan behavior set for your app.

To fix it, follow the section to disable default keyboard handling on Android.

If, for some reason, you need to keep adjustPan behavior for other parts of the app (where library does not need to handle the keyboard), you might check AvoidSoftInput.setAdjust(Pan|Resize|Nothing|Unspecified) functions.