fix(Android, Stack): Moving formsheet above keyboard #3248

t0maboro · 2025-09-25T07:42:55Z

Description

This PR improves the way the BottomSheet on Android handles the on-screen keyboard (IME). Previously, the keyboard was not respected properly - opening the keyboard could cause content to be partially or fully obscured due to incorrect handling of insets.

With this update:

We listen to dynamic bottom IME insets to track the keyboard position in real-time.
The BottomSheet's Y translation now directly reflects the current IME inset, preventing it from being overlapped by the keyboard.
Since we have implemented custom enter/exit animations (fade + slide), IME insets must be taken into account both during animations and in live state updates to avoid layout jumps.

There are two key touchpoints where we react to IME inset changes:

During enter/exit animations: When autofocus is enabled or when entering/leaving with the keyboard open, we need to align the BottomSheet's position with the keyboard height continuously.
In the onProgress callback: This listens to dynamic IME inset changes outside of enter/exit animations — e.g. when the keyboard resizes or changes without the BottomSheet visibility changing.

Priority is given to the animation layer for transforming the component's position, while the onProgress callback serves as a fallback when animations are not active. This prioritization enables us to maintain a smooth and consistent visual appearance across all lifecycle scenarios of the BottomSheet.

Fixes: #3181

Changes

Aligned the method for calculating available space for bottom sheet with Android
Fixed the height calculation on KeyboardDidHide state for fitToContents
Synchronized translationY updates between our custom entering/exiting animations with onProgress callback from insets listener.
Added a new example for testing this scenario

Screenshots / GIFs

Here you can add screenshots / GIFs documenting your change.

You can add before / after section if you're changing some behavior.

Before

test3248-main.mov

After

test3248.mov

Test code and steps to reproduce

Tested on android with Test3248

Tested with API levels 29 or higher, because I noticed another issue regarding bottom sheets on 28: https://github.com/software-mansion/react-native-screens-labs/issues/480

Checklist

Included code example that can be used to test this change
Ensured that CI passes

t0maboro · 2025-09-29T11:35:14Z

Moving back to draft for a while, because I noticed some issues with autofocus and textinput below API 30

kligarski

I had already started the review before you moved the PR to draft so I'll finish it.

This looks great! I have some remarks/questions:

Just to be sure, this is not a regression, right? (not respecting navigation bar insets)

Screen_recording_20250929_140451.mp4

Do you think we can do something about the gap between keyboard and formsheet when they're both hiding at the same time? Should we create a ticket to investigate it in the future?

Screen_recording_20250929_135928.mp4

We should probably revisit #2925 to fix this, right?

Screen_recording_20250929_140440.mp4

android/src/main/java/com/swmansion/rnscreens/ScreenStackFragment.kt

android/src/main/java/com/swmansion/rnscreens/bottomsheet/SheetDelegate.kt

t0maboro · 2025-09-29T14:13:33Z

@kligarski answering your questions:

Imo not a regression, because as a top edge I was considering top edge of the component, the same way as we'd put detent=1.0 previously. However, we should definitely consider whether this is still valid, as now we're avoiding the keyboard. cc @kkafar if you have any thoughts on that

I created a ticket on labs repo https://github.com/software-mansion/react-native-screens-labs/issues/484, but the problem here is that I'm dependent on onProgress callback, which will cause a slight delay.
For status bar, I'd prefer to continue the work in fix(Android): status bar insets for formSheet #2925 - I can take it over and adapt to this PR (until anyone has any objections of at.1 whether the status bar is a regression or not)

kligarski · 2025-09-29T14:32:01Z

@kligarski answering your questions:

Imo not a regression, because as a top edge I was considering top edge of the component, the same way as we'd put detent=1.0 previously. However, we should definitely consider whether this is still valid, as now we're avoiding the keyboard. cc @kkafar if you have any thoughts on that

I'm not sure if we're talking about the same thing: I meant the text input being placed behind navigation bar (3-button navigation at the bottom) in first fitToContents example. I checked the main and confirmed that this is not a regression so we're good.

t0maboro · 2025-09-29T14:36:11Z

@kligarski answering your questions:
Imo not a regression, because as a top edge I was considering top edge of the component, the same way as we'd put detent=1.0 previously. However, we should definitely consider whether this is still valid, as now we're avoiding the keyboard. cc @kkafar if you have any thoughts on that

I'm not sure if we're talking about the same thing: I meant the text input being placed behind navigation bar (3-button navigation at the bottom) in first fitToContents example. I checked the main and confirmed that this is not a regression so we're good.

Sorry, I read all together before answering and idk why I started thinking that 1 and 3 are connected. Good that we have an alignment on this one, but we should rethink whether this is expected now

kkafar

I'm reviewing only code right now. I'll check the runtime tomorrow.

android/src/main/java/com/swmansion/rnscreens/ScreenStackFragment.kt

kkafar · 2025-11-05T15:51:42Z

android/src/main/java/com/swmansion/rnscreens/ScreenStackFragment.kt

+        val startValueCallback = { _: Number? -> screen.height.toFloat() }
+        val evaluator = ExternalBoundaryValuesEvaluator(startValueCallback, { 0f })
+
+        return ValueAnimator.ofObject(evaluator, screen.height.toFloat(), 0f).apply {


Reading this for the first time & I don't get why on slide in animator the start value is height and target value is 0, at least passed here. I also see that there is an evaluator.

I'll update the comment if I get this

I wrote this code intitially, but I do not remember that. 😄

Oh, is it because the sheet has already target position & we translate it back to the animation start position? That might be it.

The initial sheet position is when the sheet bottom edge is equal to device's bottom edge, we're translating Y with a positive value to hide the sheet under the bottom edge of the device

kkafar · 2025-11-05T17:12:55Z

android/src/main/java/com/swmansion/rnscreens/bottomsheet/SheetDelegate.kt

+        val detents = screen.sheetDetents
+        if (detents.isEmpty()) {
+            throw IllegalStateException("[RNScreens] Cannot determine sheet detent - detents list is empty")
+        }


We should have separate data structure for detents, making sure of this invariant. Let's create ticket for this.

https://github.com/software-mansion/react-native-screens-labs/issues/536

kkafar · 2025-11-05T17:14:01Z

android/src/main/java/com/swmansion/rnscreens/bottomsheet/SheetDelegate.kt

+            throw IllegalStateException("[RNScreens] Cannot determine sheet detent - detents list is empty")
+        }
+
+        val detentValue = detents[detents.size - 1].coerceIn(0.0, 1.0)


I don't get this part. Why do you take value of the largest detent here?

This method is used only when there is keyboard present, is that right? If so, let's name it appropriately, cause right now it's not obvious at all.

e.g. computeSheetOffsetYWithIMEPresent or something.

also this place deserves its own comment, because it really defines the behaviour of the sheet -> that it expands to max detent when the keyboard shows, right?

yes, the sheet expands to its max detent; the purpose of this code is to determine whether we're able to show the full sheet or if we need to cover it partially with the keyboard, definitely deserves some description, giving the information about the final offset from bottom, to which we should animate

kkafar · 2025-11-06T10:10:31Z

What about this behaviour?

It goes up, even if there is no IME present? Can we detect such case?

Screen.Recording.2025-11-06.at.11.10.01.mov

kkafar · 2025-11-06T10:12:38Z

Also this is messed up a bit. Is this particular behaviour handled in the safe area view PR?
The text input lands under the status bar

Screen.Recording.2025-11-06.at.11.12.16.mov

kkafar

Just last code remarks.

apps/src/tests/Test3248.tsx

t0maboro · 2025-11-06T12:41:21Z

What about this behaviour?

It goes up, even if there is no IME present? Can we detect such case?

7187586 + d354569 (cleanup)

Also this is messed up a bit. Is this particular behaviour handled in the safe area view PR?
The text input lands under the status bar

As discussed internally, let's proceed with that in the PR with FormSheet - SAV fixes

@kkafar

## Description Followup for: #3248 (comment) Note: @kkafar I'm aware that it differs from what we discussed internally, but imo it may make sense to do it in the way I'm proposing here, let me know what do you think Fixes software-mansion/react-native-screens-labs#537 ## Changes - Extracted sheet animation code to a separate class ## Test code and steps to reproduce Regression testing on `Test3248` ## Checklist - [x] Included code example that can be used to test this change - [x] Ensured that CI passes

kkafar

Looks good. Great job. Thank you!

t0maboro marked this pull request as ready for review September 29, 2025 11:05

t0maboro requested review from kkafar, kligarski and kmichalikk September 29, 2025 11:05

t0maboro force-pushed the @t0maboro/keyboard-avoiding-formsheet-android branch from 39c6b3e to bda8134 Compare September 29, 2025 11:15

t0maboro changed the title ~~WIP - fix(Android, Stack): Moving formsheet above keyboard~~ fix(Android, Stack): Moving formsheet above keyboard Sep 29, 2025

t0maboro removed request for kkafar, kligarski and kmichalikk September 29, 2025 11:34

t0maboro marked this pull request as draft September 29, 2025 11:34

kligarski reviewed Sep 29, 2025

View reviewed changes

android/src/main/java/com/swmansion/rnscreens/ScreenStackFragment.kt Show resolved Hide resolved

android/src/main/java/com/swmansion/rnscreens/bottomsheet/SheetDelegate.kt Outdated Show resolved Hide resolved

t0maboro marked this pull request as ready for review September 29, 2025 14:13

t0maboro requested review from kkafar, kligarski and kmichalikk September 29, 2025 14:14

kligarski approved these changes Sep 30, 2025

View reviewed changes

t0maboro added 10 commits October 22, 2025 10:49

Minimal POC with translateY

2c72a6e

Fix initial slide in animation

739312a

Separating slide-in and inset animations

9a7e62e

Split animators logic for entering and keyboard progressing

c85c55e

Fix calculating detent on keyboardDidHide with fitToContents

2af4a0f

Drop unnecessary state listener

5f9df1d

Remove logs

2c44e39

Minor cleanup

113a0de

Add example

15d71ee

Use different API for reading insets on android 29 or lower

cf80859

kkafar reviewed Nov 5, 2025

View reviewed changes

t0maboro added 10 commits November 6, 2025 09:00

Rename

a52b93a

Rename

c935b5d

Rename

541be9d

Rename

6a5476d

Rename

58d2d1f

Rename

f1e63f2

Rename

690420f

Drop optional

08f272e

Rename + comment

bcfbf55

Fix typo

39db00f

t0maboro requested a review from kkafar November 6, 2025 09:35

kkafar reviewed Nov 6, 2025

View reviewed changes

apps/src/tests/Test3248.tsx Outdated Show resolved Hide resolved

t0maboro added 3 commits November 6, 2025 13:37

Fix onscreen keyboard case

7187586

Remove arrow functions

743d8d7

Formatting

1eaf8b0

t0maboro requested a review from kkafar November 6, 2025 12:41

Cleanup

d354569

t0maboro mentioned this pull request Nov 7, 2025

refactor(Android, Stack): Refactor sheet animation code #3378

Merged

2 tasks

t0maboro added 2 commits November 7, 2025 13:10

Linter

8278813

kkafar approved these changes Nov 7, 2025

View reviewed changes

t0maboro merged commit e609b6f into main Nov 7, 2025
5 checks passed

t0maboro deleted the @t0maboro/keyboard-avoiding-formsheet-android branch November 7, 2025 13:48

kkafar mentioned this pull request Nov 7, 2025

fix(Android): handle keyboard and formsheet together #2923

Closed

2 tasks

This was referenced Nov 7, 2025

@maciekstosio/handle android 29 wip #2936

Closed

feat(Android): keyboard avoiding form sheet #2939

Closed

Uh oh!

fix(Android, Stack): Moving formsheet above keyboard #3248

fix(Android, Stack): Moving formsheet above keyboard #3248

Conversation

t0maboro commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Screenshots / GIFs

Before

After

Test code and steps to reproduce

Checklist

Uh oh!

t0maboro commented Sep 29, 2025

Uh oh!

kligarski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

t0maboro commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kligarski commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

t0maboro commented Sep 29, 2025

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkafar Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t0maboro Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkafar commented Nov 6, 2025

Uh oh!

kkafar commented Nov 6, 2025

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

t0maboro commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

t0maboro commented Sep 25, 2025 •

edited

Loading

t0maboro commented Sep 29, 2025 •

edited

Loading

kligarski commented Sep 29, 2025 •

edited

Loading

kkafar Nov 5, 2025 •

edited

Loading

t0maboro Nov 5, 2025 •

edited

Loading

t0maboro commented Nov 6, 2025 •

edited

Loading