fix: bug with KeyboardChatScrollView + inverted + maintainVisibleScrollPosition + FlashList (#1437)

## 📜 Description

Fixed a problem with non-working `maintainVisibleScrollPosition` when
using `inverted` prop of `KeyboardChatScrollView`.

## 💡 Motivation and Context

The issue stems from the fact that we use additional `View` in
`KeyboardChatScrollView`:

```tsx
<ScrollViewComponent ref={ref} animatedProps={animatedProps} {...rest}>
  {inverted ? (
    // The only thing it can break is `StickyHeader`, but it's already broken in FlatList and other lists
    // don't support this functionality, so we can add additional view here
    // The correct fix would be to add a new prop in ScrollView that allows
    // to customize children extraction logic and skip custom view
    <View collapsable={false} nativeID="container">
      {children}
    </View>
  ) : (
    children
  )}
</ScrollViewComponent>
```

It totally breaks `maintainVisibleScrollPosition` behavior. The
algorithm is similar on both iOS/Android, but we'll use Android code
snippets for demonstration. First of all it iterates over **direct
children** of `contentView`:

```kt
for (i in config.minIndexForVisible until contentView.childCount) {
    val child = contentView.getChildAt(i)
    val position = child.y + child.height
    if (position > currentScroll || i == contentView.childCount - 1) {
        firstVisibleViewRef = WeakReference(child)
        prevFirstVisibleFrame = frame
        break
    }
}
```

So when we draw additional `View` - the algorithm becomes completely
broken. Further the code does something like this:

```kt
val deltaY = newFrame.top - prevFirstVisibleFrame.top
if (deltaY != 0) {
    scrollView.scrollToPreservingMomentum(scrollView.scrollX, scrollY + deltaY)
}
```

But this code will never work properly, because on first step we will
not be able to compute proper `prevFirstVisibleFrame` (since we have
only single `View` and this `View` is always visible).

First idea that I had in my mind was adding `TransientView` that would
substitute `childCount`/`getChildAt` and forward them down to inner
children. However it significantly increases the complexity of the app.
And I decided to dig deeper into "why exactly I added this code?".

The reason was very simple. My virtualized list example was flickering
during keyboard animation (pay attention to "So far it looks cool!"
message in the bottom of the screen):


https://github.com/user-attachments/assets/e66d119d-3818-4b10-b921-4d84af3d414c

If we check debugger we can see that this item has been recycled:

<img width="1156" height="159" alt="Screenshot 2026-04-17 at 10 57 35"
src="https://github.com/user-attachments/assets/696150da-2f44-48ba-b93b-fa8ce02ac6de"
/>

> [!IMPORTANT]
> This issue seems to be reproducible only with `FlashList` (not
`FlatList`). If I remember correctly `FlatList` tries to mount all items
if we don't provide a function for layout prediction (just do it in
batch updates). `FlashList` actually recycles items (and because of that
it has better memory footprint). So the issue is reproducible only in
`FlashList` since it recycles items.

> [!WARNING]
> I also managed to reproduce it on new arch only. Old arch works well
even without `drawDistance` specification 🤷‍♂️

I think this problem is caused by the fact that we change `translateY`
of the content and perform scroll. In this case visible items are not
the same that `FlashList` thinks are visible (because `FlashList`
doesn't know anything about `translateY` that was modified natively).

So the fix is to remove additional view and simply increase `windowSize`
in example app (I also mentioned this side effect in documentation).

Additionally I think that this fake `View` may completely break
recycling of `FlashList` because we render a single big `View` which
technically is always visible 🤷‍♂️

<hr />

So in general: rendering additional `View` may break many things
(maintainVisibleScrollPosition, recycling) so it's not a correct
solution. Current solution - remove that fake view AND increase
rendering buffer for virtualized lists.
 
Closes
#1423

## 📢 Changelog

<!-- High level overview of important changes -->
<!-- For example: fixed status bar manipulation; added new types
declarations; -->
<!-- If your changes don't affect one of platform/language below - then
remove this platform/language -->

### Docs

- mention that `inverted` prop may require enhanced `drawDistance`;

### JS

- removed additional `View` when rendering `inverted` list;

### Android

- use `contentView` directly (no first child of `contentView` anymore)
for modifying `translateY` posiiton;

## 🤔 How Has This Been Tested?

Tested manually on Pixel 7 Pro (API 36).

## 📸 Screenshots (if appropriate):

### Flickering

|Before|After|
|-------|----|
|<video
src="https://github.com/user-attachments/assets/e66d119d-3818-4b10-b921-4d84af3d414c">|<video
src="https://github.com/user-attachments/assets/16b5439b-4fb6-4c61-9921-d9704f28cf6e">|

### Auto-scrolling

|Before|After|
|-------|----|
|<video
src="https://github.com/user-attachments/assets/1390ab14-7359-4d21-b391-25a59f51bb0a">|<video
src="https://github.com/user-attachments/assets/4d2c0884-ff07-4bd8-a1da-aaa505c4ec2c">|

## 📝 Checklist

- [x] CI successfully passed
- [x] I added new mocks and corresponding unit-tests if library API was
changed

Author: kirillzyusko

FabricExample/package.json

@@ -22,7 +22,7 @@
     "@react-navigation/native": "7.1.17",
     "@react-navigation/native-stack": "7.3.26",
     "@react-navigation/stack": "7.3.6",
-    "@shopify/flash-list": "^2.2.0",
+    "@shopify/flash-list": "^2.3.1",
     "lottie-react-native": "^7.3.4",
     "react": "19.1.0",
     "react-dom": "19.1.0",

FabricExample/src/screens/Examples/KeyboardChatScrollView/VirtualizedListScrollView.tsx

@@ -69,8 +69,9 @@ const VirtualizedListScrollView = forwardRef<
     const { inverted, freeze, mode, keyboardLiftBehavior } =
       useChatConfigStore();
 
-    // on new arch only FlatList supports `inverted` prop
-    const isInvertedSupported = inverted && mode === "flat" ? inverted : false;
+    // only FlatList and FlashList supports `inverted` prop
+    const isInvertedSupported =
+      inverted && (mode === "flat" || mode === "flash") ? inverted : false;
     const onLayout = useCallback(
       (e: LayoutChangeEvent) => {
         setLayoutPass((l) => l + 1);

FabricExample/src/screens/Examples/KeyboardChatScrollView/index.tsx

@@ -8,6 +8,7 @@ import React, {
   useState,
 } from "react";
 import {
+  Dimensions,
   FlatList,
   Image,
   StyleSheet,
@@ -34,6 +35,7 @@ import styles, {
   MARGIN,
   TEXT_INPUT_HEIGHT,
   contentContainerStyle,
+  invertedContentContainerStyle,
 } from "./styles";
 import VirtualizedListScrollView, {
   type VirtualizedListScrollViewRef,
@@ -117,8 +119,18 @@ function KeyboardChatScrollViewPlayground() {
         )}
         {mode === "flash" && (
           <FlashList
-            contentContainerStyle={contentContainerStyle}
-            data={messages}
+            contentContainerStyle={
+              inverted ? invertedContentContainerStyle : contentContainerStyle
+            }
+            data={inverted ? reversedMessages : messages}
+            // use slightly bigger distance to avoid flashing for inverted case
+            // internally `KeyboardChatScrollView` re-positions content and in case
+            // of inverted it shifts it by `translateY={keyboardSize}` and adjust scroll position
+            // so real content movement can be `keyboardSize x2`, and `FlashList` may recycle wrong items
+            // using bigger distance we assure that we will not see flickering of messages
+            // during keyboard animation
+            drawDistance={Dimensions.get("screen").height}
+            inverted={inverted}
             keyExtractor={(item) => item.text}
             maintainVisibleContentPosition={{
               startRenderingFromBottom: inverted,

FabricExample/yarn.lock

@@ -1909,10 +1909,10 @@
     "@react-navigation/elements" "^2.4.6"
     color "^4.2.3"
 
-"@shopify/flash-list@^2.2.0":
-  version "2.2.0"
-  resolved "https://registry.yarnpkg.com/@shopify/flash-list/-/flash-list-2.2.0.tgz#bafd714576182681cba25fb13195dee19f5ca521"
-  integrity sha512-mL61IofcfBNRZ/qazIf+pghGULkcZUQ7EZNldH1JBbIjtDb25ADSiQrt62ZTnRz0H5+bPFEZUmN9+WChHzX8pw==
+"@shopify/flash-list@^2.3.1":
+  version "2.3.1"
+  resolved "https://registry.yarnpkg.com/@shopify/flash-list/-/flash-list-2.3.1.tgz#d4f90b1471a741a97c07d9aadbfaf200e92c86f7"
+  integrity sha512-7oktg2NQR7KAODjFoDaWe8/OBzyYbdTE3zQTrUBMxjIbxHTHN7UXRX1hX3DHk8KvtkgQdRfZOV8Gjj2l4fGrXw==
 
 "@sideway/address@^4.1.5":
   version "4.1.5"

android/src/main/java/com/reactnativekeyboardcontroller/views/ClippingScrollViewDecoratorView.kt

@@ -48,7 +48,7 @@ class ClippingScrollViewDecoratorView(
     // virtualizer calculations correct (it reads layout positions,
     // not translationY).
     val contentView = scrollView.getChildAt(0) as? ViewGroup ?: return
-    (contentView.getChildAt(0) as? ViewGroup)?.translationY = newTopInsetPx.toFloat()
+    contentView.translationY = newTopInsetPx.toFloat()
 
     scrollView.setPadding(
       scrollView.paddingLeft,

docs/docs/api/components/keyboard-chat-scroll-view.mdx

@@ -40,6 +40,10 @@ Accepts either a plain `boolean` or a [Reanimated `SharedValue<boolean>`](https:
 
 Set to `true` if your list uses the `inverted` prop (the standard pattern for chat-style lists where the newest messages appear at the bottom).
 
+:::warning Virtualized list caution
+If you're using `inverted={true}` with virtualized lists (e.g. `FlashList`), make sure to increase `drawDistance` (or any similar prop that controls how much content is rendered outside the visible area). This can help [prevent](https://github.com/kirillzyusko/react-native-keyboard-controller/pull/1437) content flashing during keyboard animations.
+:::
+
 ### `keyboardLiftBehavior`
 
 Controls how the chat content responds when the keyboard appears. Defaults to `"always"`.

docs/versioned_docs/version-1.21.0/api/components/keyboard-chat-scroll-view.mdx

@@ -40,6 +40,10 @@ Accepts either a plain `boolean` or a [Reanimated `SharedValue<boolean>`](https:
 
 Set to `true` if your list uses the `inverted` prop (the standard pattern for chat-style lists where the newest messages appear at the bottom).
 
+:::warning Virtualized list caution
+If you're using `inverted={true}` with virtualized lists (e.g. `FlashList`), make sure to increase `drawDistance` (or any similar prop that controls how much content is rendered outside the visible area). This can help [prevent](https://github.com/kirillzyusko/react-native-keyboard-controller/pull/1437) content flashing during keyboard animations.
+:::
+
 ### `keyboardLiftBehavior`
 
 Controls how the chat content responds when the keyboard appears. Defaults to `"always"`.

example/src/screens/Examples/KeyboardChatScrollView/VirtualizedListScrollView.tsx

@@ -69,7 +69,7 @@ const VirtualizedListScrollView = forwardRef<
     const { inverted, freeze, mode, keyboardLiftBehavior } =
       useChatConfigStore();
 
-    // on old arch only FlatList and FlashList supports `inverted` prop
+    // only FlatList and FlashList supports `inverted` prop
     const isInvertedSupported =
       inverted && (mode === "flat" || mode === "flash") ? inverted : false;
     const onLayout = useCallback(

example/src/screens/Examples/KeyboardChatScrollView/index.tsx

@@ -8,6 +8,7 @@ import React, {
   useState,
 } from "react";
 import {
+  Dimensions,
   FlatList,
   Image,
   StyleSheet,
@@ -127,6 +128,13 @@ function KeyboardChatScrollViewPlayground() {
               inverted ? invertedContentContainerStyle : contentContainerStyle
             }
             data={inverted ? reversedMessages : messages}
+            // use slightly bigger distance to avoid flashing for inverted case
+            // internally `KeyboardChatScrollView` re-positions content and in case
+            // of inverted it shifts it by `translateY={keyboardSize}` and adjust scroll position
+            // so real content movement can be `keyboardSize x2`, and `FlashList` may recycle wrong items
+            // using bigger distance we assure that we will not see flickering of messages
+            // during keyboard animation
+            drawDistance={Dimensions.get("screen").height}
             inverted={inverted}
             keyExtractor={(item) => item.text}
             renderItem={({ item }) => <Message {...item} />}

src/components/ScrollViewWithBottomPadding/index.tsx

@@ -1,5 +1,5 @@
 import React, { forwardRef } from "react";
-import { Platform, View } from "react-native";
+import { Platform } from "react-native";
 import Reanimated, {
   useAnimatedProps,
   useSharedValue,
@@ -125,17 +125,7 @@ const ScrollViewWithBottomPadding = forwardRef<
         style={styles.container}
       >
         <ScrollViewComponent ref={ref} animatedProps={animatedProps} {...rest}>
-          {inverted ? (
-            // The only thing it can break is `StickyHeader`, but it's already broken in FlatList and other lists
-            // don't support this functionality, so we can add additional view here
-            // The correct fix would be to add a new prop in ScrollView that allows
-            // to customize children extraction logic and skip custom view
-            <View collapsable={false} nativeID="container">
-              {children}
-            </View>
-          ) : (
-            children
-          )}
+          {children}
         </ScrollViewComponent>
       </ReanimatedClippingScrollView>
     );