feat: new behavior="translate-with-padding" for KeyboardAvoidingView (#830)

kirillzyusko · web-flow · commit fa6d67d282ce · 2025-02-24T11:36:58.000+01:00
## 📜 Description Added new `behavior="translate-with-padding"` for `KeyboardAvoidingView`. ## 💡 Motivation and Context The new mode ideally fits for chat-like applications and has very good performance. The implementation was mostly inspired by [WindowInsetsAnimation](https://github.com/android/user-interface-samples/tree/main/WindowInsetsAnimation) sample app. However when I tried to replace `translateY` to `0` and apply `paddingBottom` which is equal to previous `translateY` I had flashes on Android (mostly because of nature of Android - transform properties (e.g., `translateY`) only trigger a **repaint** (no _reflow_) and are applied **immediately**. Changes to **layout** properties like **padding** force the Android rendering system to recalculate layout (**reflow**), which can take an extra frame to resolve). So instead of switching those properties I decided to keep `translateY` and add `paddingTop` (in the end of animation to resize the container). Since we change `paddingTop` only in the beginning or in the end of animation the transition is unbelievable smooth, because we trigger layout re-calculation only once (so in terms of complexity new approach is `O(1)` vs `O(n)`). Closes #719 (comment) software-mansion/react-native-reanimated#6854 #650 (comment) ## 🔢 Things to do - write e2e tests for chat FlatList example screen (to cover new functionality with e2e tests); - update documentation page with detailed explanation of modes and when to use each of them. ## 📢 Changelog    ### JS - added new `"translate-with-padding"` behavior for `KeyboardAvoidingView` - added `useTranslateAnimation` hook; - integrate `useTranslateAnimation` with `"translate-with-padding"`; - update example app to more performant implementation; ### Docs - mention new behavior; ## 🤔 How Has This Been Tested? Tested both paper and fabric on: - iPhone 15 Pro (iOS 17.5); - Medium phone (API 35). ## 📸 Screenshots (if appropriate): ### Paper |Android|iOS| |--------|---| |<video src="https://github.com/user-attachments/assets/f8d35138-77ae-432e-a95b-97104a01b4fe">|<video src="https://github.com/user-attachments/assets/93db0cdb-4ef4-4fb0-8cd4-9ada0312ff7d">| ### Fabric |Android|iOS| |--------|---| |<video src="https://github.com/user-attachments/assets/e2398edc-d6c0-41e8-8fdc-eb95e7741f74">|<video src="https://github.com/user-attachments/assets/379567d3-5d7a-482c-81af-ab359356a11c">| ## 📝 Checklist - [x] CI successfully passed - [x] I added new mocks and corresponding unit-tests if library API was changed
diff --git a/FabricExample/package.json b/FabricExample/package.json
@@ -14,6 +14,7 @@
     "@react-native-community/blur": "^4.4.1",
     "@react-native-masked-view/masked-view": "^0.3.2",
     "@react-navigation/bottom-tabs": "^6.6.1",
+    "@react-navigation/elements": "^2.2.5",
     "@react-navigation/native": "^6.1.18",
     "@react-navigation/native-stack": "^6.11.0",
     "@react-navigation/stack": "^6.4.1",
diff --git a/FabricExample/src/screens/Examples/ReanimatedChatFlatList/index.tsx b/FabricExample/src/screens/Examples/ReanimatedChatFlatList/index.tsx
@@ -1,10 +1,7 @@
+import { useHeaderHeight } from "@react-navigation/elements";
 import React from "react";
-import { FlatList, TextInput, View } from "react-native";
-import { useKeyboardHandler } from "react-native-keyboard-controller";
-import Animated, {
-  useAnimatedStyle,
-  useSharedValue,
-} from "react-native-reanimated";
+import { FlatList, TextInput } from "react-native";
+import { KeyboardAvoidingView } from "react-native-keyboard-controller";
 
 import Message from "../../../components/Message";
 import { history } from "../../../components/Message/data";
@@ -20,41 +17,15 @@ const RenderItem: ListRenderItem<MessageProps> = ({ item, index }) => {
   return <Message key={index} {...item} />;
 };
 
-const useGradualAnimation = () => {
-  const height = useSharedValue(0);
-
-  useKeyboardHandler(
-    {
-      onMove: (e) => {
-        "worklet";
-
-        // eslint-disable-next-line react-compiler/react-compiler
-        height.value = e.height;
-      },
-      onEnd: (e) => {
-        "worklet";
-
-        height.value = e.height;
-      },
-    },
-    [],
-  );
-
-  return { height };
-};
-
 function ReanimatedChatFlatList() {
-  const { height } = useGradualAnimation();
-
-  const fakeView = useAnimatedStyle(
-    () => ({
-      height: Math.abs(height.value),
-    }),
-    [],
-  );
+  const headerHeight = useHeaderHeight();
 
   return (
-    <View style={styles.container}>
+    <KeyboardAvoidingView
+      behavior="translate-with-padding"
+      keyboardVerticalOffset={headerHeight}
+      style={styles.container}
+    >
       <FlatList
         inverted
         contentContainerStyle={styles.contentContainer}
@@ -63,8 +34,7 @@ function ReanimatedChatFlatList() {
         renderItem={RenderItem}
       />
       <TextInput style={styles.textInput} />
-      <Animated.View style={fakeView} />
-    </View>
+    </KeyboardAvoidingView>
   );
 }
 
diff --git a/FabricExample/yarn.lock b/FabricExample/yarn.lock
@@ -2367,6 +2367,13 @@
   resolved "https://registry.yarnpkg.com/@react-navigation/elements/-/elements-1.3.31.tgz#28dd802a0787bb03fc0e5be296daf1804dbebbcf"
   integrity sha512-bUzP4Awlljx5RKEExw8WYtif8EuQni2glDaieYROKTnaxsu9kEIA515sXQgUDZU4Ob12VoL7+z70uO3qrlfXcQ==
 
+"@react-navigation/elements@^2.2.5":
+  version "2.2.5"
+  resolved "https://registry.yarnpkg.com/@react-navigation/elements/-/elements-2.2.5.tgz#0e2ca76e2003e96b417a3d7c2829bf1afd69193f"
+  integrity sha512-sDhE+W14P7MNWLMxXg1MEVXwkLUpMZJGflE6nQNzLmolJQIHgcia0Mrm8uRa3bQovhxYu1UzEojLZ+caoZt7Fg==
+  dependencies:
+    color "^4.2.3"
+
 "@react-navigation/native-stack@^6.11.0":
   version "6.11.0"
   resolved "https://registry.yarnpkg.com/@react-navigation/native-stack/-/native-stack-6.11.0.tgz#a33f92cbd55dfe28fb0ba67df99aaa95240eb87c"
diff --git a/docs/docs/api/components/keyboard-avoiding-view.mdx b/docs/docs/api/components/keyboard-avoiding-view.mdx
@@ -117,6 +117,7 @@ Specify how to react to the presence of the keyboard. Could be one value of:
 - `position`
 - `padding`
 - `height`
+- `translate-with-padding`
 
 ### `contentContainerStyle`
 
diff --git a/docs/versioned_docs/version-1.16.0/api/components/keyboard-avoiding-view.mdx b/docs/versioned_docs/version-1.16.0/api/components/keyboard-avoiding-view.mdx
@@ -117,6 +117,7 @@ Specify how to react to the presence of the keyboard. Could be one value of:
 - `position`
 - `padding`
 - `height`
+- `translate-with-padding`
 
 ### `contentContainerStyle`
 
diff --git a/example/package.json b/example/package.json
@@ -15,6 +15,7 @@
     "@react-native-community/blur": "^4.4.1",
     "@react-native-masked-view/masked-view": "^0.3.2",
     "@react-navigation/bottom-tabs": "^6.6.1",
+    "@react-navigation/elements": "^2.2.5",
     "@react-navigation/native": "^6.1.18",
     "@react-navigation/native-stack": "^6.11.0",
     "@react-navigation/stack": "^6.4.1",
diff --git a/example/src/screens/Examples/ReanimatedChatFlatList/index.tsx b/example/src/screens/Examples/ReanimatedChatFlatList/index.tsx
@@ -1,10 +1,7 @@
+import { useHeaderHeight } from "@react-navigation/elements";
 import React from "react";
-import { FlatList, TextInput, View } from "react-native";
-import { useKeyboardHandler } from "react-native-keyboard-controller";
-import Animated, {
-  useAnimatedStyle,
-  useSharedValue,
-} from "react-native-reanimated";
+import { FlatList, TextInput } from "react-native";
+import { KeyboardAvoidingView } from "react-native-keyboard-controller";
 
 import Message from "../../../components/Message";
 import { history } from "../../../components/Message/data";
@@ -20,41 +17,15 @@ const RenderItem: ListRenderItem<MessageProps> = ({ item, index }) => {
   return <Message key={index} {...item} />;
 };
 
-const useGradualAnimation = () => {
-  const height = useSharedValue(0);
-
-  useKeyboardHandler(
-    {
-      onMove: (e) => {
-        "worklet";
-
-        // eslint-disable-next-line react-compiler/react-compiler
-        height.value = e.height;
-      },
-      onEnd: (e) => {
-        "worklet";
-
-        height.value = e.height;
-      },
-    },
-    [],
-  );
-
-  return { height };
-};
-
 function ReanimatedChatFlatList() {
-  const { height } = useGradualAnimation();
-
-  const fakeView = useAnimatedStyle(
-    () => ({
-      height: Math.abs(height.value),
-    }),
-    [],
-  );
+  const headerHeight = useHeaderHeight();
 
   return (
-    <View style={styles.container}>
+    <KeyboardAvoidingView
+      behavior="translate-with-padding"
+      keyboardVerticalOffset={headerHeight}
+      style={styles.container}
+    >
       <FlatList
         inverted
         contentContainerStyle={styles.contentContainer}
@@ -63,8 +34,7 @@ function ReanimatedChatFlatList() {
         renderItem={RenderItem}
       />
       <TextInput style={styles.textInput} />
-      <Animated.View style={fakeView} />
-    </View>
+    </KeyboardAvoidingView>
   );
 }
 
diff --git a/example/yarn.lock b/example/yarn.lock
@@ -2367,6 +2367,13 @@
   resolved "https://registry.yarnpkg.com/@react-navigation/elements/-/elements-1.3.31.tgz#28dd802a0787bb03fc0e5be296daf1804dbebbcf"
   integrity sha512-bUzP4Awlljx5RKEExw8WYtif8EuQni2glDaieYROKTnaxsu9kEIA515sXQgUDZU4Ob12VoL7+z70uO3qrlfXcQ==
 
+"@react-navigation/elements@^2.2.5":
+  version "2.2.5"
+  resolved "https://registry.yarnpkg.com/@react-navigation/elements/-/elements-2.2.5.tgz#0e2ca76e2003e96b417a3d7c2829bf1afd69193f"
+  integrity sha512-sDhE+W14P7MNWLMxXg1MEVXwkLUpMZJGflE6nQNzLmolJQIHgcia0Mrm8uRa3bQovhxYu1UzEojLZ+caoZt7Fg==
+  dependencies:
+    color "^4.2.3"
+
 "@react-navigation/native-stack@^6.11.0":
   version "6.11.0"
   resolved "https://registry.yarnpkg.com/@react-navigation/native-stack/-/native-stack-6.11.0.tgz#a33f92cbd55dfe28fb0ba67df99aaa95240eb87c"
diff --git a/src/components/KeyboardAvoidingView/hooks.ts b/src/components/KeyboardAvoidingView/hooks.ts
@@ -1,9 +1,12 @@
 import { useState } from "react";
+import { Platform } from "react-native";
 import { useSharedValue } from "react-native-reanimated";
 
 import { useKeyboardContext } from "../../context";
 import { useKeyboardHandler } from "../../hooks";
 
+const OS = Platform.OS;
+
 export const useKeyboardAnimation = () => {
   const { reanimated } = useKeyboardContext();
 
@@ -53,3 +56,54 @@ export const useKeyboardAnimation = () => {
 
   return { height, progress, heightWhenOpened, isClosed };
 };
+export const useTranslateAnimation = () => {
+  const { reanimated } = useKeyboardContext();
+
+  // calculate it only once on mount, to avoid `SharedValue` reads during a render
+  const [initialProgress] = useState(() => reanimated.progress.value);
+
+  const padding = useSharedValue(initialProgress);
+  const translate = useSharedValue(0);
+
+  useKeyboardHandler(
+    {
+      onStart: (e) => {
+        "worklet";
+
+        if (e.height === 0) {
+          // eslint-disable-next-line react-compiler/react-compiler
+          padding.value = 0;
+        }
+        if (OS === "ios") {
+          translate.value = e.progress;
+        }
+      },
+      onMove: (e) => {
+        "worklet";
+
+        if (OS === "android") {
+          translate.value = e.progress;
+        }
+      },
+      onInteractive: (e) => {
+        "worklet";
+
+        padding.value = 0;
+
+        translate.value = e.progress;
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        padding.value = e.progress;
+
+        if (OS === "android") {
+          translate.value = e.progress;
+        }
+      },
+    },
+    [],
+  );
+
+  return { translate, padding };
+};
diff --git a/src/components/KeyboardAvoidingView/index.tsx b/src/components/KeyboardAvoidingView/index.tsx
@@ -10,7 +10,7 @@ import Reanimated, {
 
 import { useWindowDimensions } from "../../hooks";
 
-import { useKeyboardAnimation } from "./hooks";
+import { useKeyboardAnimation, useTranslateAnimation } from "./hooks";
 
 import type { LayoutRectangle, ViewProps } from "react-native";
 
@@ -45,7 +45,7 @@ export type KeyboardAvoidingViewProps = KeyboardAvoidingViewBaseProps &
         /**
          * Specify how to react to the presence of the keyboard.
          */
-        behavior?: "height" | "padding";
+        behavior?: "height" | "padding" | "translate-with-padding";
 
         /**
          * `contentContainerStyle` is not allowed for these behaviors.
@@ -85,6 +85,7 @@ const KeyboardAvoidingView = forwardRef<
     const initialFrame = useSharedValue<LayoutRectangle | null>(null);
     const frame = useDerivedValue(() => initialFrame.value || defaultLayout);
 
+    const { translate, padding } = useTranslateAnimation();
     const keyboard = useKeyboardAnimation();
     const { height: screenHeight } = useWindowDimensions();
 
@@ -96,6 +97,14 @@ const KeyboardAvoidingView = forwardRef<
 
       return Math.max(frame.value.y + frame.value.height - keyboardY, 0);
     }, [screenHeight, keyboardVerticalOffset]);
+    const interpolateToRelativeKeyboardHeight = useCallback(
+      (value: number) => {
+        "worklet";
+
+        return interpolate(value, [0, 1], [0, relativeKeyboardHeight()]);
+      },
+      [relativeKeyboardHeight],
+    );
 
     const onLayoutWorklet = useCallback((layout: LayoutRectangle) => {
       "worklet";
@@ -114,11 +123,11 @@ const KeyboardAvoidingView = forwardRef<
     );
 
     const animatedStyle = useAnimatedStyle(() => {
-      const bottom = interpolate(
+      const bottom = interpolateToRelativeKeyboardHeight(
         keyboard.progress.value,
-        [0, 1],
-        [0, relativeKeyboardHeight()],
       );
+      const translateY = interpolateToRelativeKeyboardHeight(translate.value);
+      const paddingBottom = interpolateToRelativeKeyboardHeight(padding.value);
       const bottomHeight = enabled ? bottom : 0;
 
       switch (behavior) {
@@ -138,10 +147,16 @@ const KeyboardAvoidingView = forwardRef<
         case "padding":
           return { paddingBottom: bottomHeight };
 
+        case "translate-with-padding":
+          return {
+            paddingTop: paddingBottom,
+            transform: [{ translateY: -translateY }],
+          };
+
         default:
           return {};
       }
-    }, [behavior, enabled, relativeKeyboardHeight]);
+    }, [behavior, enabled, interpolateToRelativeKeyboardHeight]);
     const isPositionBehavior = behavior === "position";
     const containerStyle = isPositionBehavior ? contentContainerStyle : style;
     const combinedStyles = useMemo(
