feat: extraContentPadding prop (#1332)

## 📜 Description

Added `extraContentPadding` prop for `KeyboardChatScrollView` component.

## 💡 Motivation and Context

This prop is very useful when you want to extend scrollable range and
re-arrange the content so that it takes the same position as before
(relatively). Theoretically "re-arrange" functionality must be
configurable, but I tested many apps and what I can tell is that it
looks like almost always this "re-arrange" respects
`keyboardLiftBehavior` prop. Later we can introduce additional prop to
have a better control, but for now we keep it simple.

I was thinking on whether to make this prop a `SharedValue` or a plain
value and I decided to make it `SharedValue` because:
- theoretically we may do all work on UI thread, i. e. synchronously
detect "input growth" and synchronously adjust position;
- we may want to change position with animation (with plain number we
would have to add `animated` prop or smth like that);
- we may want to have a customizable animation (duration, easing, so
SharedValue can be a perfect driver).

We also heavily use reanimated hooks internally, so integration with
`SharedValue` looks very natural.

I intentionally didn't want to modify original hooks and I extended
functionality using new hook: `useExtraContentPadding`. This new hook
extends `contentInsets` + adjust scroll position. Maybe we'll et
conflicts between hook in future, but at the moment it's extendable 😎

Closes
#1324

## 📢 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

- added new prop description;
- added new prop usage in guide page;

### JS

- added `extraContentPadding` prop for `KeyboardChatScrollView`
component
- cover new functionality by unit tests;

## 🤔 How Has This Been Tested?

Tested manually on:
- iPhone 17 Pro (iOS 26.2);
- Pixel 7 Pro (Android 16)

## 📸 Screenshots (if appropriate):

|Android|iOS|
|-------|-----|
|<video
src="https://github.com/user-attachments/assets/00b90e82-a410-41d2-9f5d-6a7d71330ff5">|<video
src="https://github.com/user-attachments/assets/a919b334-83fe-48a5-afdf-76406ce00f66">|

## 📝 Checklist

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

Author: kirillzyusko

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

@@ -15,14 +15,20 @@ import {
   invertedContentContainerStyle,
 } from "./styles";
 
+import type { SharedValue } from "react-native-reanimated";
+
+type VirtualizedListScrollViewProps = ScrollViewProps & {
+  extraContentPadding?: SharedValue<number>;
+};
+
 export type VirtualizedListScrollViewRef = React.ElementRef<
   typeof KeyboardChatScrollView
 >;
 
 const VirtualizedListScrollView = forwardRef<
   VirtualizedListScrollViewRef,
-  ScrollViewProps
->(({ onLayout: onLayoutProp, ...props }, ref) => {
+  VirtualizedListScrollViewProps
+>(({ onLayout: onLayoutProp, extraContentPadding, ...props }, ref) => {
   const [layoutPass, setLayoutPass] = useState(0);
   const { bottom } = useSafeAreaInsets();
   const chatKitOffset = bottom - MARGIN;
@@ -50,6 +56,7 @@ const VirtualizedListScrollView = forwardRef<
             : contentContainerStyle
         }
         contentInsetAdjustmentBehavior="never"
+        extraContentPadding={extraContentPadding}
         freeze={freeze}
         inverted={isInvertedSupported}
         keyboardDismissMode="interactive"

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

@@ -19,6 +19,7 @@ import {
   KeyboardGestureArea,
   KeyboardStickyView,
 } from "react-native-keyboard-controller";
+import { useSharedValue } from "react-native-reanimated";
 import {
   SafeAreaView,
   useSafeAreaInsets,
@@ -49,6 +50,7 @@ function KeyboardChatScrollViewPlayground() {
   const textInputRef = useRef<TextInput>(null);
   const textRef = useRef("");
   const [inputHeight, setInputHeight] = useState(TEXT_INPUT_HEIGHT);
+  const extraContentPadding = useSharedValue(0);
   const { inverted, messages, reversedMessages, addMessage, mode } =
     useChatConfigStore();
   const { bottom } = useSafeAreaInsets();
@@ -58,9 +60,16 @@ function KeyboardChatScrollViewPlayground() {
     [bottom],
   );
 
-  const onInputLayoutChanged = useCallback((e: LayoutChangeEvent) => {
-    setInputHeight(e.nativeEvent.layout.height);
-  }, []);
+  const onInputLayoutChanged = useCallback(
+    (e: LayoutChangeEvent) => {
+      const height = e.nativeEvent.layout.height;
+
+      // eslint-disable-next-line react-compiler/react-compiler
+      extraContentPadding.value = Math.max(height - TEXT_INPUT_HEIGHT, 0);
+      setInputHeight(height);
+    },
+    [extraContentPadding],
+  );
   const onInput = useCallback((text: string) => {
     textRef.current = text;
   }, []);
@@ -90,8 +99,13 @@ function KeyboardChatScrollViewPlayground() {
   }, [messages]);
 
   const memoList = useCallback(
-    (props: ScrollViewProps) => <VirtualizedListScrollView {...props} />,
-    [],
+    (props: ScrollViewProps) => (
+      <VirtualizedListScrollView
+        {...props}
+        extraContentPadding={extraContentPadding}
+      />
+    ),
+    [extraContentPadding],
   );
 
   return (
@@ -124,7 +138,7 @@ function KeyboardChatScrollViewPlayground() {
               startRenderingFromBottom: inverted,
             }}
             renderItem={({ item }) => <Message {...item} />}
-            renderScrollComponent={VirtualizedListScrollView}
+            renderScrollComponent={memoList}
           />
         )}
         {mode === "flat" && (
@@ -138,7 +152,10 @@ function KeyboardChatScrollViewPlayground() {
           />
         )}
         {mode === "scroll" && (
-          <VirtualizedListScrollView ref={scrollRef}>
+          <VirtualizedListScrollView
+            ref={scrollRef}
+            extraContentPadding={extraContentPadding}
+          >
             {messages.map((message, index) => (
               <Message key={index} {...message} />
             ))}

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

@@ -84,6 +84,23 @@ The distance between the bottom of the screen and the `ScrollView`. When the key
 
 This is useful when the input is not at the very bottom of the screen — for example, when the `ScrollView` sits above a **safe area** inset, **bottom tabs**, or **any other fixed-height element**. In that case, set `offset` to the height of the elements between the `ScrollView` and the bottom of the screen.
 
+### `extraContentPadding`
+
+A [Reanimated `SharedValue<number>`](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/) representing additional padding introduced by an element **outside** the keyboard — for example, a growing multiline `TextInput` inside a `KeyboardStickyView`.
+
+When this value changes, `KeyboardChatScrollView` does two things:
+
+1. **Extends the scrollable range** — the extra amount is added to `contentInset`, keeping all content reachable.
+2. **Adjusts the scroll position** — conditionally, based on `keyboardLiftBehavior`, so the bottom messages stay visible as the input grows.
+
+:::tip When to use it?
+Use `extraContentPadding` whenever an element that is **not** the keyboard changes the amount of space the chat list has to work with. The most common case is a multiline text input that grows as the user types.
+:::
+
+:::note
+The value must be a `SharedValue` (from `useSharedValue`) — not a plain number — so that changes are tracked on the UI thread without triggering a React re-render.
+:::
+
 ## Usage with virtualized lists
 
 `KeyboardChatScrollView` doesn't ship with built-in wrappers for third-party virtualized list libraries, but since all of them (`FlatList`, `FlashList`, `LegendList`) accept a custom scroll component, integration is straightforward.

docs/docs/guides/building-chat-app.mdx

@@ -197,6 +197,69 @@ const onKeyboardPress = () => {
 
 When `freeze` is `true`, all keyboard-driven layout changes (padding, content offset, scroll position) are paused.
 
+### Handling a growing multiline input
+
+If your composer has a `multiline` `TextInput` that grows as the user types, you need to tell `KeyboardChatScrollView` about the extra space it takes up — otherwise the component doesn't know the scrollable range has changed and the bottom messages can get clipped under the input.
+
+Pass a `SharedValue<number>` via the `extraContentPadding` prop. Update it in the `TextInput`'s `onLayout` callback whenever the height changes:
+
+```tsx
+import { useCallback } from "react";
+import { TextInput, type LayoutChangeEvent } from "react-native";
+import { useSharedValue, withTiming } from "react-native-reanimated";
+
+const MIN_INPUT_HEIGHT = 36;
+
+function ChatScreen() {
+  const extraContentPadding = useSharedValue(0);
+
+  const onInputLayout = useCallback(
+    (e: LayoutChangeEvent) => {
+      const height = e.nativeEvent.layout.height;
+
+      extraContentPadding.value = withTiming(
+        Math.max(height - MIN_INPUT_HEIGHT, 0),
+        { duration: 250 },
+      );
+    },
+    [extraContentPadding],
+  );
+
+  return (
+    <>
+      <KeyboardChatScrollView extraContentPadding={extraContentPadding}>
+        {/* ...messages... */}
+      </KeyboardChatScrollView>
+      <KeyboardStickyView>
+        <TextInput multiline onLayout={onInputLayout} />
+      </KeyboardStickyView>
+    </>
+  );
+}
+```
+
+The value represents the **delta** above the baseline input height. When the input is at its minimum height the value is `0`; each line of growth adds to it. The component uses this value to:
+
+1. Extend the scrollable range so the last messages aren't hidden under the taller input.
+2. Scroll the list down (based on `keyboardLiftBehavior`) so the bottom messages stay visible.
+
+:::note Using with virtualized lists
+When using `extraContentPadding` with `FlatList`, `FlashList`, or `LegendList`, pass the shared value through your wrapper component — both to `KeyboardChatScrollView` and to `useCallback` dependencies so the reference is stable:
+
+```tsx
+const renderScrollComponent = useCallback(
+  (props: ScrollViewProps) => (
+    <VirtualizedListScrollView
+      {...props}
+      extraContentPadding={extraContentPadding}
+    />
+  ),
+  [extraContentPadding],
+);
+```
+
+:::
+
 ## Using with virtualized lists
 
 For production chat apps you'll likely use a virtualized list (`FlatList`, `FlashList`, or `LegendList`) instead of a plain `ScrollView`. All of these accept a custom scroll component, making integration straightforward.
@@ -312,13 +375,15 @@ import {
   TextInput,
   TouchableOpacity,
   View,
+  type LayoutChangeEvent,
   type ScrollViewProps,
 } from "react-native";
 import {
   KeyboardChatScrollView,
   KeyboardGestureArea,
   KeyboardStickyView,
 } from "react-native-keyboard-controller";
+import { useSharedValue, withTiming } from "react-native-reanimated";
 import {
   SafeAreaView,
   useSafeAreaInsets,
@@ -355,10 +420,13 @@ function ChatScreen() {
   const textRef = useRef("");
   const [messages, setMessages] = useState(INITIAL_MESSAGES);
   const { bottom } = useSafeAreaInsets();
+  const extraContentPadding = useSharedValue(0);
 
   const renderScrollComponent = useCallback(
-    (props: ScrollViewProps) => <ChatScrollView {...props} />,
-    [],
+    (props: ScrollViewProps) => (
+      <ChatScrollView {...props} extraContentPadding={extraContentPadding} />
+    ),
+    [extraContentPadding],
   );
 
   const onSend = useCallback(() => {
@@ -370,6 +438,16 @@ function ChatScreen() {
     textRef.current = "";
   }, []);
 
+  const onInputLayout = useCallback(
+    (e: LayoutChangeEvent) => {
+      extraContentPadding.value = withTiming(
+        Math.max(e.nativeEvent.layout.height - INPUT_HEIGHT, 0),
+        { duration: 250 },
+      );
+    },
+    [extraContentPadding],
+  );
+
   return (
     <SafeAreaView edges={["bottom"]} style={styles.container}>
       <KeyboardGestureArea
@@ -397,6 +475,7 @@ function ChatScreen() {
             placeholder="Type a message..."
             style={styles.input}
             onChangeText={(text) => (textRef.current = text)}
+            onLayout={onInputLayout}
           />
           <TouchableOpacity onPress={onSend}>
             <Text>Send</Text>

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

@@ -15,14 +15,20 @@ import {
   invertedContentContainerStyle,
 } from "./styles";
 
+import type { SharedValue } from "react-native-reanimated";
+
+type VirtualizedListScrollViewProps = ScrollViewProps & {
+  extraContentPadding?: SharedValue<number>;
+};
+
 export type VirtualizedListScrollViewRef = React.ElementRef<
   typeof KeyboardChatScrollView
 >;
 
 const VirtualizedListScrollView = forwardRef<
   VirtualizedListScrollViewRef,
-  ScrollViewProps
->(({ onLayout: onLayoutProp, ...props }, ref) => {
+  VirtualizedListScrollViewProps
+>(({ onLayout: onLayoutProp, extraContentPadding, ...props }, ref) => {
   const [layoutPass, setLayoutPass] = useState(0);
   const { bottom } = useSafeAreaInsets();
   const chatKitOffset = bottom - MARGIN;
@@ -49,6 +55,7 @@ const VirtualizedListScrollView = forwardRef<
           inverted ? invertedContentContainerStyle : contentContainerStyle
         }
         contentInsetAdjustmentBehavior="never"
+        extraContentPadding={extraContentPadding}
         freeze={freeze}
         inverted={isInvertedSupported}
         keyboardDismissMode="interactive"

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

@@ -19,6 +19,7 @@ import {
   KeyboardGestureArea,
   KeyboardStickyView,
 } from "react-native-keyboard-controller";
+import { useSharedValue, withTiming } from "react-native-reanimated";
 import {
   SafeAreaView,
   useSafeAreaInsets,
@@ -50,6 +51,7 @@ function KeyboardChatScrollViewPlayground() {
   const textInputRef = useRef<TextInput>(null);
   const textRef = useRef("");
   const [inputHeight, setInputHeight] = useState(TEXT_INPUT_HEIGHT);
+  const extraContentPadding = useSharedValue(0);
   const { inverted, messages, reversedMessages, addMessage, mode } =
     useChatConfigStore();
   const { bottom } = useSafeAreaInsets();
@@ -59,9 +61,19 @@ function KeyboardChatScrollViewPlayground() {
     [bottom],
   );
 
-  const onInputLayoutChanged = useCallback((e: LayoutChangeEvent) => {
-    setInputHeight(e.nativeEvent.layout.height);
-  }, []);
+  const onInputLayoutChanged = useCallback(
+    (e: LayoutChangeEvent) => {
+      const height = e.nativeEvent.layout.height;
+
+      // eslint-disable-next-line react-compiler/react-compiler
+      extraContentPadding.value = withTiming(
+        Math.max(height - TEXT_INPUT_HEIGHT, 0),
+        { duration: 250 },
+      );
+      setInputHeight(height);
+    },
+    [extraContentPadding],
+  );
   const onInput = useCallback((text: string) => {
     textRef.current = text;
   }, []);
@@ -91,8 +103,13 @@ function KeyboardChatScrollViewPlayground() {
   }, [messages]);
 
   const memoList = useCallback(
-    (props: ScrollViewProps) => <VirtualizedListScrollView {...props} />,
-    [],
+    (props: ScrollViewProps) => (
+      <VirtualizedListScrollView
+        {...props}
+        extraContentPadding={extraContentPadding}
+      />
+    ),
+    [extraContentPadding],
   );
 
   return (
@@ -124,7 +141,7 @@ function KeyboardChatScrollViewPlayground() {
             inverted={inverted}
             keyExtractor={(item) => item.text}
             renderItem={({ item }) => <Message {...item} />}
-            renderScrollComponent={VirtualizedListScrollView}
+            renderScrollComponent={memoList}
           />
         )}
         {mode === "flat" && (
@@ -138,7 +155,10 @@ function KeyboardChatScrollViewPlayground() {
           />
         )}
         {mode === "scroll" && (
-          <VirtualizedListScrollView ref={scrollRef}>
+          <VirtualizedListScrollView
+            ref={scrollRef}
+            extraContentPadding={extraContentPadding}
+          >
             {messages.map((message, index) => (
               <Message key={index} {...message} />
             ))}