KeyboardAwareScrollView behavior difference after 1.21.0

[olitynskyi-mtb]

Context

In the 1.21.0 release post, KeyboardAwareScrollView is described as moving from a hidden bottom View to a contentInset-based implementation:

• Blog post: https://kirillzyusko.github.io/react-native-keyboard-controller/blog/chat-scroll-view
• Relevant section: "Improved KeyboardAwareScrollView"

The post explains that before 1.21.0, KeyboardAwareScrollView added a hidden bottom View inside the scroll content, and starting from 1.21.0 it uses contentInset on iOS and ClippingScrollView on Android.

Observed behavior difference

This is not only an internal implementation change. For KeyboardAwareScrollView, it also changes the visual behavior on screens with short content or flex-based layouts.

Before 1.21.0

• Keyboard space was created by a real spacer view inside the scroll content.
• Because that spacer participated in layout, the content could visually reflow.
• In practice, layouts using flex: 1, flexGrow, gap, or justifyContent: "space-between" could compress or redistribute free space as the keyboard opened.

Starting from 1.21.0

• Keyboard space is added through scroll insets instead of a real child view.
• The scrollable area grows, but the content layout itself does not reflow in the same way.
• On screens with content shorter than the viewport, this can look like extra blank scrollable space is added below the content instead of the old visual "compression" behavior.

Why this matters

For some apps, the old KeyboardAwareScrollView behavior was actually desirable. Even though it caused layout participation, it also produced a specific visual result that some form screens relied on.

So from a consumer point of view, this can feel like a behavior change rather than just a performance improvement.

Question

Was this difference in KeyboardAwareScrollView semantics intentional?

More specifically:

1. Was it expected that KeyboardAwareScrollView would stop visually reflowing short/flex layouts and instead extend only the scrollable area?
2. Would it make sense to document this more explicitly as a behavioral change for KeyboardAwareScrollView, not only as an internal improvement?
3. Would you be open to supporting both strategies, for example a spacer mode for the pre-1.21.0 behavior and an inset mode for the layout-free behavior?

Why we are asking

We fully understand the motivation behind the contentInset approach: fewer layout recalculations, more stable animations, and better cross-platform parity.

At the same time, on real screens the previous KeyboardAwareScrollView behavior could be visually preferable, especially for forms with small amounts of content where the layout itself was expected to respond to keyboard space.

[kirillzyusko]

Appreciate the effort you put into description of this problem ❤️

Would you be open to supporting both strategies, for example a spacer mode for the pre-1.21.0 behavior and an inset mode for the layout-free behavior?

@olitynskyi-mtb yes, I've been thinking about this too. For example in #1368 this migration is also causing the problem. And even for compatibility mode - I think it's better to support both modes.

When I implemented this in the beginning I didn't think that people could use the component in such way and that was a desirable behavior (not a side effect).

If I add property like mode="insets|layout" - will it be enough for your purposes?

[litinskii]

If I add property like mode="insets|layout" - will it be enough for your purposes?

Everything works fine for me.

I’m also adding a patch I experimented with:

<KeyboardAwareScrollView keyboardSpaceMode="spacer" />

You can find it here — maybe it will help you as well:

staged.patch

[kirillzyusko]

Got it @litinskii

Do you need to have a frame changing every keyboard frame? Because otherwise the animation will have like a 1 frame, right? I. e. there will be no animation at all?

[litinskii]

Yes, I think frame by frame updates are still needed.

What I meant is probably not "animation vs no animation", but what exactly is being updated every frame.

If I understand it correctly, before 1.21.0 KeyboardAwareScrollView was affecting a real spacer inside the content, so layout could reflow.
Now it seems to affect contentInset, so the scroll area changes, but layout does not reflow in the same way.

I may be wrong on the internals, but from the outside it does look like a visible behavior change.

[kirillzyusko]

Thanks @litinskii

Could you please confirm that #1420 fixes this issue?

[litinskii]

@kirillzyusko

2026-04-02.14.09.37.mov

Works, but there is a significant delay.

Seems that you use heigh from currentKeyboardFrameHeight but it is no updated while move.

with this

2026-04-02.14.27.35.mov

[sergeyzhukov]

same issue, waiting for fix in main

[bigcupcoffee]

Also same here, in our case we do style={{ ...StyleSheet.absoluteFill, ... }} and it doesn't even go to the top-most view anymore, so It basically ignores it and doesn't position absolutely

[sergeyzhukov]

@kirillzyusko any ETA for this fix?

[kirillzyusko]

@sergeyzhukov I'll merge and release it next Monday 🤞