feat: `minimumContentPadding` prop on `KeyboardChatScrollView` by trcoffman · Pull Request #1344 · kirillzyusko/react-native-keyboard-controller

trcoffman · 2026-03-05T19:18:46Z

📜 Description

Added new minimumContentPadding prop to KeyboardChatScrollView. This is to provide a mechanism for positioning the latest user message at the top of the screen when building AI chat apps with streaming responses.

💡 Motivation and Context

Schematically all the process can be shown as this:

The main idea is that minimumContentPadding adds a scrollable range in ScrollView, so that "just sent" message can be scrolled up and be visible from the top (typical functionality in AI apps).

However we need to define a strategy how new property reacts when keyboard appears/disappears. For that we define two stategies:

minimumContentPadding > extraContentPadding + keyboardHeight - content position is not changing in this case
minimumContentPadding ><extraContentPadding + keyboardHeight - content position is changes by delta between left/right operand.

This is a typical AI flow. Both ChatGPT/Claude works in this way, so I don't think we need to customize it somehow (maybe in future, but not now).

Closes #1333

📢 Changelog

Docs

added docs about new props;

JS

added applyWorkaroundForContentInsetHitTestBug prop;
added minimumContentPadding prop;
cover new functionality with unit tests;
supply separate indicatorInsets props to have a better control of scroll indicator position.

iOS

implemented code applyWorkaroundForContentInsetHitTestBug prop;

Android

added no-op setter for applyWorkaroundForContentInsetHitTestBug` prop;

🤔 How Has This Been Tested?

Manually testing on iOS and Android with the AI LegendList Chat example that I included in this PR.

You can type 'a', 'b', 'c', or 'd' in the chat to get shorter vs longer replies from the AI to test how things work with the blankSize.

Tested on:

Pixel 7 Pro;
iPhone 17 Pro (iOS 26.2).

📸 Screenshots (if appropriate):

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-03-03.at.16.31.29.mp4

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-03-03.at.16.32.00.mp4

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-03-03.at.16.32.50.mp4

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-03-03.at.16.33.04.mp4

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-03-03.at.16.34.52.mp4

📝 Checklist

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

github-actions · 2026-03-05T19:56:24Z

📊 Package size report

Current size	Target Size	Difference
299974 bytes	286926 bytes	13048 bytes 📈

argos-ci · 2026-03-07T22:53:23Z

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	1 changed	Mar 10, 2026, 9:55 AM

Add a blankSize prop that will ensure that it's possible to put the latest user message right at the top of the screen when building an AI chat app. KeyboardChatLegendList: Fix imports after reverting to beta.32

Fix Android keyboard close/open asymmetry and apply binary blank absorption Two changes to the Android useChatKeyboard hook: 1. Apply the same binary blank absorption from the iOS fix: only absorb blank space when fully visible (visibleFraction >= 1), otherwise shift content by the full keyboard amount. Previously Android used linear scaling which caused partial occlusion when blank was partially visible. 2. Fix close animation overshooting on non-inverted lists. The close path was computing the theoretical scroll displacement (keyboard height minus blank absorption) to undo the open shift. But when the open shift was clamped by maxScroll, the theoretical value exceeded the actual shift, causing close to move content down more than open moved it up. Record the actual scroll displacement at the end of the open animation (scroll.value - offsetBeforeScroll) and use that for the close calculation. This makes open/close symmetric regardless of clamping.

…lView Previously, scrollIndicatorInsets matched contentInset, which included blankSize. This caused the scroll indicator to end halfway down the screen when blankSize was large. Add a scrollIndicatorPadding prop to ScrollViewWithBottomPadding that computes indicator insets from keyboard + extraContentPadding only, excluding blankSize. User-supplied scrollIndicatorInsets.bottom/top are now additive adjustments (previously silently ignored). Update AILegendListChat example to pass a negative safe area bottom adjustment for apps that render into the unsafe area.

… iOS Implements a runtime swizzling fix for React Native 0.81+ bug where ScrollView's contentInset area fails to respond to touch events. This prevents users from initiating scroll gestures by touching the inset padding area, which is critical for chat UX patterns where contentInset positions messages at the top of the screen. ## Problem React Native's RCTScrollViewComponentView.betterHitTest returns the container view (self) instead of the underlying UIScrollView instance when the touch is in the contentInset area. This causes touch events to be intercepted by the container, preventing the scroll view from receiving gestures. Upstream issue: facebook/react-native#54123 ## Solution Uses Objective-C runtime method swizzling to override hitTest:withEvent: on the ScrollView's container view. The fix mirrors the upstream patch: - Calls the original hitTest:withEvent: implementation - When the result is self (the container) - which is the bug - dynamically finds and returns the UIScrollView child instead - Otherwise preserves the original result (subviews, nil, etc.) Key implementation detail: the UIScrollView is looked up dynamically at hit-test time rather than captured during swizzling. This ensures the fix works across React Native hot reloads and full refreshes where the view hierarchy is recreated but the swizzled class persists. Implementation follows the same pattern as PR kirillzyusko#1336's scrollRectToVisible fix: dynamic subclass creation with idempotent prefix check, applied lazily in didMoveToWindow. ## Benefits ✅ Users can now scroll by touching contentInset area ✅ Interactive content (Pressables, buttons, inputs) continues to work normally ✅ Survives React Native hot reloads and full refreshes ✅ Fixes chat UX where messages need top positioning via contentInset ✅ Non-breaking: defensive implementation returns early if structure unexpected ✅ Compatible with existing scrollRectToVisible noop fix ✅ Zero-cost for apps not using ClippingScrollView ✅ Provides immediate relief while waiting for upstream React Native fix ## Performance Considerations The dynamic scrollView lookup only executes when: - The original hitTest returns the container (empty space/contentInset area) - NOT when touching actual content (messages, buttons, etc.) Cost: iterating through container's direct subviews (typically 1-3 views) - UIScrollView + maybe scroll indicators - Just pointer comparisons and class checks - Negligible performance impact ## Risks and Considerations ⚠️ Runtime swizzling: Fragile if React Native's view hierarchy changes Mitigation: Defensive checks, silently returns if container not found ⚠️ Dynamic lookup on every hit test in contentInset area: Small overhead Mitigation: Only 1-3 subviews to check, only runs for empty space touches ⚠️ React Native version variations: Different RN versions may have different hierarchies Mitigation: Graceful degradation - no fix applied but doesn't break ⚠️ Calling original implementation: Assumes it's safe to invoke Mitigation: Standard ObjC pattern, same lifetime guarantees as the view ## Testing Recommendations - Test contentInset with top/bottom/left/right values - Verify touch in contentInset area initiates scroll - Verify interactive elements (Pressables, buttons, inputs) remain functional - Test with inverted ScrollViews (chat pattern) - Verify behavior persists after hot reload - Verify behavior persists after full refresh - Test keyboard interactions remain functional - Verify no console warnings - Test on iOS 17+ with React Native 0.81+ ## Technical Details Implementation in ClippingScrollViewDecoratorViewManager.mm: - Added KCApplyFixedHitTest() function that swizzles hitTest:withEvent: - Modified didMoveToWindow() to apply both fixes - Captures original IMP and calls it via function pointer - Conditional: if (result == self) lookup and return UIScrollView child - Dynamic lookup avoids stale references across RN refreshes - Uses KC_FixedHitTest_ prefix for idempotent check

… the data array

…ding

When closing the keyboard on iOS, after an earlier commit that fixed android behavior, it made iOS worse than it was in the first commit of this PR. This improves iOS.

…sible text otherwise)

kirillzyusko · 2026-03-10T10:08:01Z

This is amazing! I can't express how grateful I am to you for making this a reality! ❤️

kirillzyusko self-assigned this Mar 5, 2026

kirillzyusko self-requested a review March 5, 2026 19:44

kirillzyusko added enhancement New feature or request KeyboardChatScrollView 💬 Anything about chat functionality labels Mar 5, 2026

trcoffman force-pushed the feature/blank-size branch 2 times, most recently from 06cc264 to 629b694 Compare March 5, 2026 22:35

kirillzyusko reviewed Mar 6, 2026

View reviewed changes

kirillzyusko added the 🍎 iOS iOS specific label Mar 6, 2026

kirillzyusko reviewed Mar 6, 2026

View reviewed changes

Comment thread src/components/KeyboardChatScrollView/useChatKeyboard/__tests__/closing.android.spec.ts Outdated

trcoffman force-pushed the feature/blank-size branch 2 times, most recently from fb9d88f to 50a444c Compare March 6, 2026 23:59

kirillzyusko marked this pull request as ready for review March 7, 2026 22:48

kirillzyusko added documentation Improvements or additions to documentation 🤖 android Android specific labels Mar 7, 2026

kirillzyusko reviewed Mar 7, 2026

View reviewed changes

kirillzyusko changed the title ~~DRAFT: Feature: blankSize prop on KeyboardChatScrollView~~ feat: minimumContentPadding prop on KeyboardChatScrollView Mar 7, 2026

trcoffman added 12 commits March 9, 2026 10:10

Feature: blankSize prop on KeyboardChatScrollView

852815b

Add a blankSize prop that will ensure that it's possible to put the latest user message right at the top of the screen when building an AI chat app. KeyboardChatLegendList: Fix imports after reverting to beta.32

AI Chat Example: Try and trigger layout shift by streaming content in…

0c4185d

… the data array

AI Chat Example: Get rid of placeholder state to fix layout shift

b658cb0

Add upstream issue link to KCApplyFixedHitTest

5b5de81

Import existing sv helper instead of redefining it

41da56b

Replace ecp abbreviation with extraContentPadding

0ced1e8

Remove unnecessary default wrappers for blankSize and extraContentPad…

e466913

…ding

Remove "in pixels" from blankSize doc comment

6b374dd

Rename indicatorPad to indicatorPadding

662c0be

trcoffman added 15 commits March 9, 2026 10:10

Move styles to separate file in AILegendListChat

687e81c

Replace keyboard dismiss logic with KeyboardController.dismiss()

36238ec

Make hitTest swizzling opt-in

4a13e10

Rename blankSize to minimumContentPadding

b8f2aa8

Fix missing onEnd call in Android keyboard close regression test

54d7cac

Docs

bcc16a5

Fix iOS Keyboard closing behavior

5831fb8

When closing the keyboard on iOS, after an earlier commit that fixed android behavior, it made iOS worse than it was in the first commit of this PR. This improves iOS.

Improve test title for never non-inverted close clamping test

4a665d3

docs improvements

d0807f8

Rename scrollEff to scrollEffective

8a8995e

Make applyWorkaroundForContentInsetHitTestBug false by default

af0eeb8

Hoist sv test helper to src/__fixtures__

29fdfaf

lint autofix

a3d0a32

fix detekt

32f5ff9

Run clang-format

1b2d38e

trcoffman force-pushed the feature/blank-size branch from a7f010f to 1b2d38e Compare March 9, 2026 18:26

kirillzyusko and others added 6 commits March 9, 2026 19:45

fix: package build

887d1ce

fix: prettier

8c41a3d

fix: detekt

ab7e754

Copy example to legacy architecture example app

8cd5afc

Upgrade legacy architecture example to @legendapp/list v3

83b2f17

fix: specify black color (paper + dark theme on Android produces invi…

3594ffc

…sible text otherwise)

kirillzyusko approved these changes Mar 10, 2026

View reviewed changes

kirillzyusko added the tests You added or changed unit tests label Mar 10, 2026

kirillzyusko merged commit 7f32767 into kirillzyusko:main Mar 10, 2026
34 of 36 checks passed

kirillzyusko added the 🚨 requires API changes 🚨 Changes that requires changes in library API label Mar 13, 2026

Uh oh!

Conversation

trcoffman commented Mar 5, 2026 • edited by kirillzyusko Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📜 Description

💡 Motivation and Context

📢 Changelog

Docs

JS

iOS

Android

🤔 How Has This Been Tested?

📸 Screenshots (if appropriate):

📝 Checklist

Uh oh!

github-actions Bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Package size report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

argos-ci Bot commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kirillzyusko commented Mar 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

trcoffman commented Mar 5, 2026 •

edited by kirillzyusko

Loading

github-actions Bot commented Mar 5, 2026 •

edited

Loading

argos-ci Bot commented Mar 7, 2026 •

edited

Loading