Improving iOS keyboard avoidance using keyboardLayoutGuide

[mhoran]

Avoiding the on-screen keyboard on iOS is a challenge. There are many options, including React Native's KeyboardAvoidingView; ScrollView option automaticallyAdjustKeyboardInsets, Reanimated's useAnimatedKeyboard, and react-native-keyboard-controller. All the aforementioned options rely on keyboard notifications to follow the keyboard. Since iOS moved to an out-of-process model, notifications are now delivered asynchronously (Keep up with the keyboard - WWDC23), which has resulted in various issues. For example, the UIKeyboardWillShowNotification notification does not always include an accurate end frame. Library authors have put workarounds in place, but each iOS update is a chance for potential regressions which have to be tracked down and fixed.

iOS 15 introduced the Keyboard Layout Guide. The Keyboard Layout Guide makes it incredibly easy to track the on-screen keyboard. However, since it is constraint based, it is not compatible with React Native's layout model out of the box. Supporting the Keyboard Layout Guide in React Native would be beneficial as it supports all "detached" keyboard types (undocked, split and floating); does not require coordinate space conversion to support Slide Over and Stage Manager; and does does not share the notification issues that impact current implementations. Using the Keyboard Layout Guide would also make it possible to introduce configuration similar to Android's windowSoftInputMode option, with support for both adjustPan and adjustResize.

I have had some luck using the Keyboard Layout Guide in my app. I created an Expo Module that provides an alternative KeyboardAvoidingView. The native code takes the children and adds them to a container subview. It then sets constraints on that subview, with the container bottomAnchor constrained to the keyboardLayoutGuide topAnchor when the keyboard is near the bottom of the screen (necessary to support the Shortcuts Bar). When the keyboard is opened, because the container heightAnchor is constrained to the KeyboardAvoidingView component height, the container subview is shifted along the Y-axis. In order to keep the scroll view content accessible, I set contentInset and scrollIndicatorInsets on the UIScrollView. This is similar to the automaticallyAdjustKeyboardInsets implementation, except the entire view is shifted upwards in addition to setting insets.

Most things seem to work fine with this approach. For example, measure and measureInWindow both use native methods and as such, are aware of the shift in the Y axis. However, measureLayout relies on the shadow tree layout, and is not aware of the shift (as is documented). Another downside of this approach is that the ScrollView and subsequently FlatList are not aware of the portion of content that is off-screen. scrollToIndex with viewPosition is inaccurate, and FlatList viewability callbacks provide incorrect information. However, automaticallyAdjustKeyboardInsets is subject to the same issues.

Alternatively, I have found that the bounds observer is called immediately just as the keyboard is about to open -- and the corresponding view also has an active animation. I was able to send this into JavaScript and animate padding of the KeyboardAvoidingView. However, there is a delay, and the animation lags a few frames behind the keyboard. React Native's Keyboard observer has the same issue. Unfortunately the performance of interactive dismissal is also pretty poor, since the keyboard height is being sent from native to JS and then back to native to update the padding.

This is where I need help. I think the latter option is likely the best way forward. If there were a way to update the KeyboardAvoidingView padding from the native side, we could wrap that update in UIView.animate and there should be no lag. Updating interactive dismissal padding in native would also be desirable, to avoid the round trip to JS. However, I'm not sure how to do this, or if it's even possible.

From there, we could either implement a KeyboardAvoidingView that works similar to today -- where the views are added as children and the keyboard is avoided with padding. Alternatively, the entire React Native app could be wrapped and setFrame used to send the constrained height into React Native. However, this is all beyond what I understand so I would love some feedback on how best to proceed.

[kirillzyusko]

Hello, creator of react-native-keyboard-controller is here 👋

Alternatively, the entire React Native app could be wrapped and setFrame used to send the constrained height into React Native.

If I understand correctly you want to wrap entire app in kind of KeyboardAvoidingView? If yes, then I don't think it's a good idea - while it may work fine for "chat-like" apps, such approach may produce hard-to-fix issues for "big-form" apps (when input is placed somewhere in top of the screen, you focus it, and if you resize the container, then focused input may move higher and become invisible). This is why KeyboardAwareScrollView components exist.

From there, we could either implement a KeyboardAvoidingView that works similar to today -- where the views are added as children and the keyboard is avoided with padding.

As you pointed out before such approach also will come with its own set of challenges. We'll need to send a corresponding update to shadow nodes, virtualised lists also must be notified about changes, etc.

Initially when I just started with designing react-native-keyboard-controller I had two options:

• simply propagate events from a native side to JS and give developers a full control over animation events;
• handle everything on a native side (and such solution already exist, it's react-native-avoid-softinput).

After considering all nuances I decided to give a try and implement a first approach just because a communication with JS might be needed anyway and you (as a developer) have a more control over it.

Thanks to reanimated we can propagate all these events to worklet handlers and synchronously modify layout for given views/perform synchronous scroll etc. - everything on UI thread! And it indeed works:

ScreenRecording_01-16-2025.11-26-05.AM_1.MP4

At least on iOS modifying padding/height seems to work fine. On Android I can see a delay but I think it's an Android limitation (Android experts feel free to correct me).

May I ask you where exactly you experience a problem using react-native-keyboard-controller? You can reach out to me via discord (nickname is kiryl.ziusko) and we can discuss everything there (maybe there is indeed a bug in react-native-keyboard-controller and I'll be glad to fix it 😊).

And last but not least - the solution "let's move everything to native using native primitives" may not always work fine and come with its own limitations. For example InputAccessoryView - the initial idea to re-use a native primitive was a brilliant, however this component has some critical issues, such as not supporting multiline/growing inputs, unability to specify a different element location (it kind of forces you to have it in the bottom of the screen to make sure that interactive dismissal works correctly), having strange mount animations if you use ViewController based navigation etc.

I'm not saying that your proposed solution is bad, just trying to understand what exactly can not be fixed by current ecosystem, whether it's possible to fix current ecosystem to support your use-case and trying to anticipate further challenges with a new approach 🙂

[cipolleschi]

@kirillzyusko small off-topic (and sorry to derail a little the conversation) but we are having reports of react-native-keyboard-controller degrading the performance on app that are migrating to the New Architecture.
Do you mind having a look at that, whenever you have time?

[mhoran]

👋 first let me just say that react-native-keyboard-controller is fantastic, and provided much insight as I started down the long and windy road of improving keyboard behavior for React Native on iOS.

If I understand correctly you want to wrap entire app in kind of KeyboardAvoidingView? If yes, then I don't think it's a good idea - while it may work fine for "chat-like" apps, such approach may produce hard-to-fix issues for "big-form" apps (when input is placed somewhere in top of the screen, you focus it, and if you resize the container, then focused input may move higher and become invisible). This is why KeyboardAwareScrollView components exist.

I believe that there should be options (see Android's three modes -- resize, pan, or nothing); however, keyboard avoiding is something that I expected to work out of the box in React Native (after ~16 years of native Android development.) I now know that this is ultimately due to the difference in direction that Apple versus Google went with regards to the keyboard; where Android has built in behavior to move the view out of the way, Apple has left this to the developer. React Native simply follows the same pattern.

I think there are many ways forward with the Keyboard Layout Guide. However, I believe that the Keyboard Layout Guide provides the best path forward when compared to using keyboard notifications. I have encountered numerous issues with keyboard notifications in the latest iPadOS 18.2 release. Notifications with incorrect end frame information (which you've addressed in react-native-keyboard-controller, and I've addressed in useAnimatedKeyboard), missing notifications, etc. The Keyboard Layout Guide (while seemingly implemented using those same notifications) does not have the same problems.

In an ideal world, constraints could just be applied to the corresponding React Native views and all would work fine. However, I don't think that will work, given the React Native layout model. So the three options presented above could be explored. The implementation I have rolled out on my main branch is that which shifts the child components along the Y-axis. This has excellent performance, and the shifted view 100% matches the keyboard location at all times. It has the downsides mentioned above, where the ScrollView does not know that it is off-screen.

I believe there are ways to send in the keyboard offset to React Native, but they are beyond my expertise. react-native-avoid-softinput may provide some inspiration. But unless the view is animated by the window server, any alternative implementations will always be playing catchup with any changes that Apple may make. Both react-native-keyboard-controller and useAnimatedKeyboard do their best to approximate the animation curve, and generally do so quite well. But if that curve ever changes (which it has in the past), things will break. Native animations don't have that issue.

May I ask you where exactly you experience a problem using react-native-keyboard-controller? You can reach out to me via discord (nickname is kiryl.ziusko) and we can discuss everything there (maybe there is indeed a bug in react-native-keyboard-controller and I'll be glad to fix it 😊).

Please see the below screen recordings regarding KeyboardAvoidingView behavior='padding' performance, on both Paper and Fabric. While sometimes the performance is fine, the more complicated the content within the FlatList, the worse the performance becomes. This is particularly an issue with an inverted FlatList, I believe due to the work that has to be done to render the view. Since the native animations aren't redrawing the view in the same way, they do not have this performance issue (React Native KeyboardAvoidingView is nice and smooth, but has other issues.)

react-native-keyboard-controller on Paper:

keyboard-controller-paper.mp4

react-native-keyboard-controller on Fabric:

keyboard-controller-fabric.mp4

Compare to the Keyboard Layout Guide, where the view is pinned perfectly to the top of the keyboard (there is a gap at the beginning, due to the safe area insets):

keyboard-layout-guide.mp4

Another concern I have with both react-native-keyboard-controller and useAnimatedKeyboard is their use of the underlying keyboard view to address various notification inconsistencies and track the keyboard during interactive dismissal. I suspect this will stop working at some point in the not too distant future. With the move to an out of process architecture, I'm surprised it even still works today. I have also seen app store rejects in the past when referencing these private classes, and while Apple seems to be turning a blind eye today, that could change at any moment.

react-native-keyboard-controller could move to using the Keyboard Layout Guide instead of keyboard notifications to track the keyboard as I've experimented with in the animate-keyboard-js branch. This would avoid the issues with the keyboard view and address the issues with the keyboard notifications. However, it would still require trying to approximate the animation curve, and have the same issues with animated padding as mentioned above.