Feature: Improvements to automaticallyAdjustKeyboardInsets

[adamaveray]

Summary:

This is a reopened version of #35224 by @isidoro98 which was closed without explanation, updated to resolve new merge conflicts and now includes an example in the RN-Tester app. Aside from that it is unchanged. Here is @isidoro98's description from their original PR:

This PR builds on top of #31402, which introduced the automaticallyAdjustsScrollIndicatorInsets functionality. It aims to fix one of RN's longstanding pain point regarding the keyboard.

The changes provide a better way of handling the ScrollView offset when a keyboard opens. Currently, when a keyboard opens we apply an offset to the Scrollview that matches the size of the keyboard. This approach is great if we are using an InputAccessoryView but if we have multiple TextInputs in a ScrollView; offsetting the content by the size of the keyboard doesn't yield the best user experience.

Changelog:

[iOS] [Changed] - Scroll ScrollView text fields into view with automaticallyAdjustsScrollIndicatorInsets

Test Plan:

The videos below compare the current and proposed behaviors for the following code:

<ScrollView
  automaticallyAdjustKeyboardInsets
  keyboardDismissMode="interactive">
  {[...Array(10).keys()].map(item => (
    <CustomTextInput placeholder={item.toString()} key={item} />
  ))}
</ScrollView>

Current behaviour	Proposal

As can be seen in the video, the current behavior applies an offset to the ScrollView content regardless of where the TextInput sits on the screen.

The proposal checks if the TextInput will be covered by the keyboard, and only then applies an offset. The offset applied is not the full size of the keyboard but instead only the required amount so that the TextInput is a specific distance above the top of the keyboard (customizable using the new bottomKeyboardOffset prop). This achieves a less "jumpy" experience for the user.

The proposal doesn't change the behavior of the ScrollView offset when an InputAccessory view is used, since it checks if the TextField that triggered the keyboard is a descendant of the ScrollView or not.

Why not use other existing solutions?

RN ecosystem offers other alternatives for dealing with a keyboard inside a ScrollView, such as a KeyboardAvoidingView or using third party libraries like react-native-keyboard-aware-scroll-view. But as shown in the recordings below, these solutions don't provide the smoothness or behavior that can be achieved with automaticallyAdjustsScrollIndicatorInsets.

KeyboardAvoidingView	rn-keyboard-aware-scroll-view

As shown in the videos, the TextInput is hidden by the keyboard for a split second before becoming visible.

Code for the videos above:

// KeyboardAvoidingView
<KeyboardAvoidingView
  style={{flex: 1, flexDirection: 'column', justifyContent: 'center'}}
  behavior="padding"
  enabled>
  <ScrollView>
    {[...Array(10).keys()].map(item => (
      <CustomTextInput placeholder={item.toString()} key={item} />
    ))}
  </ScrollView>
</KeyboardAvoidingView>

// rn-keyboard-aware-scroll-view
<KeyboardAwareScrollView>
 {[...Array(10).keys()].map(item => (
   <CustomTextInput placeholder={item.toString()} key={item} />
 ))}
</KeyboardAwareScrollView>

[facebook-github-bot]

Hi @adamaveray!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[javache]

Why can't bottomKeyboardOffset be implemented using a marginBottom on the TextInput component?

[adamaveray]

@javache Thanks for reviewing and for your feedback. This PR was initially put together by another contributor so I wasn't aware of the private API usage. I've overhauled how it's all implemented now to avoid that and to remove the niche bottomKeyboardOffset value. It now replicates native iOS focus behaviour as closely as I could get it, which can be tested in the updated RN Tester ScrollViewKeyboardInsets screen. Please let me know if you have any feedback on the changes!

[analysis-bot]

Platform	Engine	Arch	Size (bytes)	Diff
android	hermes	arm64-v8a	8,969,902	+8
android	hermes	armeabi-v7a	n/a	--
android	hermes	x86	n/a	--
android	hermes	x86_64	n/a	--
android	jsc	arm64-v8a	9,563,165	+7
android	jsc	armeabi-v7a	n/a	--
android	jsc	x86	n/a	--
android	jsc	x86_64	n/a	--

Base commit: 9faf256
Branch: main

[javache]

@philIip Any concerns with this? You mentioned some changes coming to keyboard layout events with iOS17.

[adamaveray]

@javache Thanks for the additional review; I've made the requested changes and also done some additional testing & updates to more closely replicate the native bottom keyboard offset amount (which I initially thought was due to an empty selection but have since found it's actually single line aka UITextField vs multiline aka UITextView). Please let me know if you have any more feedback.

[adamaveray]

@javache Just checking in to see if there are any other issues you can see with this PR that are standing in the way of it potentially being merged?

[javache]

Thanks for adding the example (and sorry for the delay)! This mostly looks good to me, but would like to clarify what the coordinates used are relative to.

[adamaveray]

Thanks for following up! I've implemented those requests & suggestions, let me know if you have any other feedback 🙌

[javache]

This looks good to merge now, but there are conflicts with main in RCTBaseTextInputView.m. Could you resolve those?

[adamaveray]

@javache The merge conflicts should be resolved now. Let me know if anything else needs updating!

[facebook-github-bot]

@javache has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator.

[facebook-github-bot]

@javache merged this pull request in 9ca1660.

[javache]

Thanks for contributing! It'd be great if you could make this feature compatible with the new architecture too.