Skip to content

fix: KeyboardChatScrollView + new reanimated compatibility - #1629

Merged
kirillzyusko merged 2 commits into
mainfrom
feat/kcsv-new-rea-compatibility
Sep 8, 2026
Merged

kirillzyusko merged 2 commits into
mainfrom
feat/kcsv-new-rea-compatibility

Conversation

@kirillzyusko

@kirillzyusko kirillzyusko commented Sep 7, 2026 •

Copy link
Copy Markdown
Owner

📜 Description

Fix iOS KeyboardChatScrollView scroll jumps with Reanimated 4.6 while preserving initial and subsequent JS contentOffset.y values.

Initialize the existing offset shared value and scroll state from contentOffset.y, include the initialized contentOffset in the first useAnimatedProps evaluation, and synchronize later JS changes into the same shared value with useEffect.

The prevContentOffsetY guard remains: inset-only updates must not replay a previous scroll command.

💡 Motivation and Context

Closes #1623 #1609

#1496 fixed an initial-position regression by skipping the first animated contentOffset evaluation. Before that fix, our shared value started at 0, so the first animated props overwrote a JS offset such as { x: 0, y: 500 } with { x: 0, y: 0 }.

The upstream history explains why this became a problem now. Reanimated #8529 introduced synchronization of settled animation values back to React. Before Reanimated #10140, that synchronization spread the entire settled bag into both props and style, so a late contentOffset still reached the native component as a prop. Reanimated #10140 correctly separated the two to prevent animated styles from leaking into unrelated component props. It exposed our dependency on that previous behavior.

Skipping that prop now causes a problem with Reanimated 4.6's settled-animation synchronization. Reanimated identifies animated props by the keys present in their initial evaluation. A contentOffset introduced only during keyboard movement is absent from those keys, so it is synchronized as a style instead of a top-level prop. Once Reanimated releases the settled entry from its props registry, a subsequent React commit can reset the native offset. Typing into a controlled input exposes this as the list dropping behind the keyboard (#1623).

The replacement addresses both cases:

  • Mount: JS y = 500 seeds both the animated target and the tracked scroll position. The first animated props contain contentOffset: { x: 0, y: 500 }, so they preserve the requested position and identify the prop to Reanimated.
  • Later JS update: changing the prop to y = 700 updates the existing shared value through useEffect; the animated props then apply 700.
  • Keyboard movement and later React commits: Reanimated synchronizes the settled offset as a prop, preserving the keyboard-adjusted position.

📢 Changelog

JS

  • Initialize KeyboardChatScrollView's animated offset and scroll state from the supplied contentOffset.y.
  • Synchronize subsequent JS contentOffset.y updates with the animated offset.

iOS

  • Fix the list jumping behind the keyboard after React commits with Reanimated 4.6.
  • Preserve nonzero initial scroll offsets without skipping the initial animated prop.

🤔 How Has This Been Tested?

Recordings use FabricExample, a dedicated iPhone 17 simulator running iOS 26.2, and Metro 8084. Native build/dependencies come from feat/rn-0.87 (React Native 0.87.1, React 19.2.3, Reanimated 4.6.0, Worklets 0.12.1). After the two baseline recordings, the checkout is switched to feat/kcsv-new-rea-compatibility for the fixed recordings, retaining the same native build and installed dependencies.

The native app was built successfully with Xcode. The same demo source and Metro configuration were retained for all recordings; the library changes are the five files in this PR (869a0c4). No changes to Reanimated were introduced for the comparison.

Runtime flags: FORCE_REACT_RENDER_FOR_SETTLED_ANIMATIONS=true, USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS=true, and DISABLE_COMMIT_PAUSING_MECHANISM=false. The reproduction branch already includes a native patch making pauseReanimatedCommits() a no-op; that patch stayed identical in every recording. These are results for that reproduction environment.

Temporary logging captured native onScroll events and Reanimated's initial animated props, settled state, and outgoing React props. The loggers only recorded values; they did not update React state or scroll the list.

Case Before With this PR
#1496: mount with JS y=500 With the original #1496 skip removed, initial animated props contain y=0; the video starts at row 1 instead of row 9. Initial animated props contain y=500; row 9 is visible immediately.
Later JS offset update — Changing JS y to 700 produces a native scroll event at 700 and settledProps.contentOffset.y=700.
#1623: open keyboard, wait for settling, then type Test With the original #1496 fix present, native y changes from -317 to 0 on typing. contentInset.top stays 318; the latest messages fall behind the keyboard. The last native offset stays -317, with no reset event; the latest messages remain above the keyboard during typing.
Settled classification in #1623 contentOffset is absent from the initial keys and ends up in settledStyle. The initial keys include contentOffset; settledProps and outgoing React props retain { x: 0, y: -317 }.

Code used for #1496

A focused temporary FabricExample/src/PR1629OffsetExample.tsx screen was used. The first button mounts the list with y = 500; the second changes the JS prop to 700. Each row is 60 points high, making the starting position visible in the recording. The full screen is included below so the initial-offset and later-update checks can be repeated.

PR1629OffsetExample.tsx
import React, { useState } from "react";
import { Button, StatusBar, StyleSheet, Text, View } from "react-native";
import {
  KeyboardChatScrollView,
  KeyboardProvider,
} from "react-native-keyboard-controller";
import {
  SafeAreaProvider,
  SafeAreaView,
  initialWindowMetrics,
} from "react-native-safe-area-context";

function OffsetExample() {
  const [mounted, setMounted] = useState(false);
  const [y, setY] = useState(500);

  return (
    <SafeAreaView style={styles.screen}>
      <Text style={styles.title}>Initial contentOffset · #1496</Text>
      <Text style={styles.label}>JS contentOffset: {`{ x: 0, y: ${y} }`}</Text>
      <View style={styles.buttons}>
        <Button title="Mount at 500" onPress={() => setMounted(true)} />
        <Button title="JS offset → 700" onPress={() => setY(700)} />
      </View>
      {mounted ? (
        <KeyboardChatScrollView
          automaticallyAdjustContentInsets={false}
          contentInsetAdjustmentBehavior="never"
          contentOffset={{ x: 0, y }}
          testID="offset.scroll"
          onScroll={(event) => {
            console.log("[PR1629 offset]", event.nativeEvent.contentOffset.y);
          }}
        >
          {Array.from({ length: 40 }, (_, index) => (
            <View key={index} style={styles.row}>
              <Text style={styles.rowText}>
                Row {index + 1} · y = {index * 60}
              </Text>
            </View>
          ))}
        </KeyboardChatScrollView>
      ) : (
        <View style={styles.empty}>
          <Text style={styles.hint}>Mount with y = 500.</Text>
          <Text style={styles.hint}>Row 9 should be at the top.</Text>
        </View>
      )}
    </SafeAreaView>
  );
}

export default function App() {
  return (
    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
      <KeyboardProvider>
        <StatusBar barStyle="dark-content" />
        <OffsetExample />
      </KeyboardProvider>
    </SafeAreaProvider>
  );
}

const styles = StyleSheet.create({
  screen: { flex: 1, backgroundColor: "white" },
  title: { fontSize: 21, fontWeight: "600", padding: 16 },
  label: { fontSize: 16, paddingHorizontal: 16, paddingBottom: 12 },
  buttons: {
    flexDirection: "row",
    justifyContent: "space-around",
    paddingBottom: 12,
  },
  empty: { flex: 1, alignItems: "center", justifyContent: "center" },
  hint: { fontSize: 18, color: "#526173", marginBottom: 8 },
  row: {
    height: 60,
    backgroundColor: "#e8eff8",
    borderBottomWidth: 2,
    borderBottomColor: "white",
    justifyContent: "center",
    paddingHorizontal: 20,
  },
  rowText: { fontSize: 18, color: "#172c49" },
});

Code used for #1623

Used the existing Chat Kit / KeyboardChatScrollViewPlayground example:

  • FabricExample/src/screens/Examples/KeyboardChatScrollView/index.tsx
  • FabricExample/src/screens/Examples/KeyboardChatScrollView/VirtualizedListScrollView.tsx
  • Existing data.ts, store.ts, and config.tsx in that directory.

Open Chat Kit in its default mode first. After it mounts, select Use Flat List, enable Toggle inverted, and leave keyboardLiftBehavior="always". For the recordings these same existing store setters were called through the debugger after mounting:

const config = useChatConfigStore.getState();
config.setMode("flat");
config.setInverted(true);

The example already uses a controlled TextInput (value={text}, onChangeText={onInput} → setText(value)) and a FlatList whose renderScrollComponent renders KeyboardChatScrollView. The latter receives inverted, contentInsetAdjustmentBehavior="never", and offset={bottom - MARGIN}. On this simulator the configured offset is 34 - 16 = 18. The recorded keyboard-adjusted position is y=-317, and the inverted list's effective top inset is 318.

Focus the input, wait for the animation and settled synchronization, then type Test. Both chat videos begin with the keyboard already open and settled so the change caused by typing is easy to compare. Only an onScroll logger was added to the existing scroll wrapper, forwarding the event to the original callback.

📸 Screenshots (if appropriate):

Before

#1496 — original fix removed #1623 — original #1496 fix present
1-before1496.mp4
2-before1623.mp4
JS requests y=500, but the first animated props overwrite it with 0: row 1 appears. After the keyboard settles, typing Test resets y=-317 to 0. The latest messages drop behind the keyboard while the inset stays 318.

After

#1496 — initial offset and later JS changes #1623 — position survives React commits
3-after1496.mp4
4-after1623.mp4
Mounting preserves y=500 (row 9). Updating the JS prop to 700 scrolls to the requested position. The same input sequence keeps the latest messages above the keyboard, with the offset remaining -317.

📝 Checklist

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

@kirillzyusko kirillzyusko self-assigned this Sep 7, 2026
@kirillzyusko kirillzyusko added 🐛 bug Something isn't working 🍎 iOS iOS specific KeyboardChatScrollView 💬 Anything about chat functionality labels Sep 7, 2026
@github-actions

github-actions Bot commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

📊 Package size report

Current size Target Size Difference
338118 bytes 337634 bytes 484 bytes 📈

@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

LGTM

@kirillzyusko
kirillzyusko merged commit 2f90cc4 into main Sep 8, 2026
18 checks passed
@kirillzyusko
kirillzyusko deleted the feat/kcsv-new-rea-compatibility branch September 8, 2026 12:37
chrisnojima added a commit to keybase/client that referenced this pull request Sep 8, 2026
Replaces our one-line `result.contentOffset = undefined` patch with the
upstream fix, kirillzyusko/react-native-keyboard-controller#1629, merged to
main but not in a release yet (1.22.4 is still latest), so it stays a patch.

Both fixes turn on the same property: Reanimated 4.6 classifies a settled
animated value as a prop or a style using only the keys present in the FIRST
animatedProps evaluation, and a key that shows up later is filed as a style,
which switches on the settled-props render path and re-renders a stale
contentInset of 0 over the real props, so UIKit clamps contentOffset to 0.
Ours declared the key while still swallowing the value. Upstream stops
swallowing entirely: contentOffsetY is seeded from the ScrollView's own
contentOffset.y (threaded through useChatKeyboard and useScrollState), so the
first evaluation can emit a real contentOffset instead of clobbering the
list's initial scroll position with {x:0,y:0} — which was the reason the
swallow existed. prevContentOffsetY starts null, so the key is always in the
first evaluation.

Upstream's version is the better one: it also carries contentOffset.x, and
fixes the initial-offset case for direct ScrollViewWithBottomPadding users
rather than only for us.

Patch regenerated with --include 'src/'; its +/- lines are identical to the
upstream PR.
chrisnojima added a commit to keybase/client that referenced this pull request Sep 8, 2026
…ntOffset fix (#29599)

* chore(deps): routine bumps

expo 57.0.21, react-native-worklets 0.12.2, babel-preset-expo 57.0.11,
eslint 10.10.0, typescript-eslint 8.70.0, @playwright/test 1.63.0,
wdio/webdriverio 9.31.7, @rolldown/plugin-babel 0.2.4; protocol
@types/node 26.5.0; react-native-kb react-native-builder-bob 0.43.1.

Resolutions: drop the now-redundant **/deepmerge-ts entry (^8.0.0 resolves
to 8.0.2 on its own) and add **/mocha/diff so mocha's diff@^7.0.0 picks up
8.0.4 (GHSA-73rr-hh4g-fpgx).

* docs(skill): note **/mocha/diff as a known-needed resolution

* fix(chat): take upstream's keyboard-controller fix instead of our own

Replaces our one-line `result.contentOffset = undefined` patch with the
upstream fix, kirillzyusko/react-native-keyboard-controller#1629, merged to
main but not in a release yet (1.22.4 is still latest), so it stays a patch.

Both fixes turn on the same property: Reanimated 4.6 classifies a settled
animated value as a prop or a style using only the keys present in the FIRST
animatedProps evaluation, and a key that shows up later is filed as a style,
which switches on the settled-props render path and re-renders a stale
contentInset of 0 over the real props, so UIKit clamps contentOffset to 0.
Ours declared the key while still swallowing the value. Upstream stops
swallowing entirely: contentOffsetY is seeded from the ScrollView's own
contentOffset.y (threaded through useChatKeyboard and useScrollState), so the
first evaluation can emit a real contentOffset instead of clobbering the
list's initial scroll position with {x:0,y:0} — which was the reason the
swallow existed. prevContentOffsetY starts null, so the key is always in the
first evaluation.

Upstream's version is the better one: it also carries contentOffset.x, and
fixes the initial-offset case for direct ScrollViewWithBottomPadding users
rather than only for us.

Patch regenerated with --include 'src/'; its +/- lines are identical to the
upstream PR.
ahalekelly added a commit to ahalekelly/t3code that referenced this pull request Sep 27, 2026
Reanimated 4.6 files settled animated-prop keys as style unless they appear
in the first useAnimatedProps evaluation, so cleanup reset the keyboard
integration's late contentOffset and active conversations lost their scroll
position (software-mansion/react-native-reanimated#10560). Keyboard-controller
1.22.5 emits contentOffset in the first evaluation
(kirillzyusko/react-native-keyboard-controller#1629), so the Reanimated patch
is no longer needed.

The keyboard-controller patch is rebased onto 1.22.5. Its onInteractive
handler now also sets 1.22.5's interactive-dismissal marker, and the lib
builds import the reanimated hooks through the package's own wrapper.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🐛 bug Something isn't working 🍎 iOS iOS specific KeyboardChatScrollView 💬 Anything about chat functionality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

KeyboardChatScrollView: a React commit resets contentInset, UIKit clamps contentOffset, and the list drops behind the keyboard (iOS/Fabric)

1 participant