fix: add `automaticOffset` prop for correct KAV positioning in modals by thomasttvo · Pull Request #1346 · kirillzyusko/react-native-keyboard-controller

thomasttvo · 2026-03-08T07:16:09Z

Problem

KeyboardAvoidingView doesn't work correctly in pageSheet modals on iOS because onLayout returns parent-relative coordinates. In a modal, the parent's y=0 doesn't correspond to screen y=0, so the keyboard overlap calculation uses incorrect positions — resulting in the keyboard covering the input or the view being offset incorrectly.

This is an iOS-specific issue. On Android, modals use a separate Dialog window, but measureInWindow (backed by getLocationOnScreen()) already returns correct absolute screen coordinates regardless of which window the view is in.

Solution

Add an opt-in automaticOffset prop (default false) that gates the measureInWindow behavior. This preserves backward compatibility — existing users who set keyboardVerticalOffset to their header height continue to work unchanged.

When automaticOffset={true}:

Uses measureInWindow instead of onLayout to get absolute screen coordinates, so the view's position is correctly detected in modals, behind navigation headers, etc.
keyboardVerticalOffset becomes purely additive extra space rather than compensation for unknown positioning — the default of 0 works correctly out of the box.

When automaticOffset={false} (default):

Behavior is identical to before this PR — uses onLayout parent-relative coordinates, and keyboardVerticalOffset must be set to the header height manually.

Uses the existing useCombinedRef hook to maintain both the internal ref (needed for measureInWindow) and the forwarded ref from the consumer.

Example app

Added a new "KeyboardAvoidingView Automatic" example screen (KeyboardAvoidingViewAutomatic) to showcase automaticOffset behavior:

Demonstrates all three behavior modes (padding, height, position)
Auto/Manual toggle to compare automaticOffset={true} vs automaticOffset={false}
Includes a pageSheet Modal to test the modal positioning fix
Configurable keyboardVerticalOffset toggle (+0, +50, +100)
Reusable KAVContent component shared between regular screen and modal

No changes to the existing KAV example screen or E2E tests.

Test Plan

iOS (iPhone 16 simulator), automaticOffset={true}, keyboardVerticalOffset={0}:

✅ Regular screen — all content visible above keyboard (padding, position modes)
✅ Modal — all content visible above keyboard (padding, position modes)

automaticOffset={false} (default), keyboardVerticalOffset={100}:

✅ Regular screen — same behavior as before this PR
✅ RN implementation — same behavior as before this PR

Fixes #867

KeyboardAvoidingView uses onLayout to get the view's frame, but onLayout returns parent-relative coordinates. In pageSheet modals, the parent's y=0 doesn't correspond to screen y=0, causing the keyboard avoidance calculation to use incorrect absolute positions. This commit fixes two issues: 1. Use measureInWindow instead of onLayout to get absolute screen coordinates. This ensures frame.y reflects the actual screen position, not the parent-relative position. 2. Compensate for the gap below pageSheet modals. In pageSheet presentation, the modal doesn't extend to the screen bottom, but the keyboard covers this gap. The overlap calculation now treats the view as extending to the screen bottom when it detects a modal-like configuration (gap > 0, gap < keyboard height, view > 50% of screen). A combinedRef is used to maintain both the internal ref (needed for measureInWindow) and the forwarded ref from the consumer. Fixes kirillzyusko#867 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Type useRef as View | null to avoid the MutableRefObject cast. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

measureInWindow already provides absolute screen coordinates, making the modal gap compensation unnecessary. The heuristic was compensating for onLayout returning parent-relative y=0 in modals, but that's now fixed at the source. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-08T10:39:49Z

📊 Package size report

Current size	Target Size	Difference
301688 bytes	300025 bytes	1663 bytes 📈

kirillzyusko · 2026-03-08T12:35:10Z

Thank you @thomasttvo for your PR

Unfortunately I can not merge it as is. Try to open example app and check the difference between package/RN implementations. You will see that package implementation will push the content significantly higher than it's expected to do. Ideally RN and package implementation should produce identical visual result.

This is a breaking change and we should understand what's causing this and fix it before a merge 🤞

You can also download e2e artifacts to see what exactly doesn't work...

thomasttvo · 2026-03-08T17:42:24Z

hey @kirillzyusko sorry about that! I meant to put this PR back in a WIP state since there's some significant changes to it since it's opened. Let me check what's going on with these issues and get back to you. Thank you for your patience!

…ation With measureInWindow, frame.y is already in absolute screen coordinates, making keyboardVerticalOffset redundant in the formula. Removing it fixes over-compensation on regular screens while maintaining correct behavior in modals. Also adds modal test case to the example app and uses the existing useCombinedRef hook instead of a manual ref callback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

With measureInWindow, the view's absolute position is already captured in frame.y. keyboardVerticalOffset is now purely additive extra offset rather than compensation for unknown view position. Update example to use offset=0 since nav bar is handled automatically. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Cycles through 0, 50, 100 to demonstrate the additive offset behavior. Shows "+N" in the header bar. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

With measureInWindow, navigation headers and modals are handled automatically. keyboardVerticalOffset is now purely additive extra offset — no need to pass useHeaderHeight() or compensate manually. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

thomasttvo · 2026-03-08T20:11:31Z

@kirillzyusko ready for review!

I tested everything manually and verified it works locally, but I may have missed a few details. Let me know if you spot anything or have any feedback on the changes.

argos-ci · 2026-03-09T13:24:21Z

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

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Mar 11, 2026, 9:02 AM

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

measureInWindow can return stale y=0 when onLayout fires during a modal's slide-up animation. This caused height and position modes to under/over-compensate in modals. Two fixes: 1. onLayoutWorklet for height mode now allows position (x, y) updates while preserving the original height — prevents stale y without reintroducing the height feedback loop. 2. Re-measure absolute position on keyboard start via useKeyboardHandler. By the time the user focuses an input, the modal animation is complete and measureInWindow returns the correct coordinates. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

useKeyboardAnimation and useTranslateAnimation already call useKeyboardHandler (which includes useResizeMode). The reMeasure handler only needs event subscription, not the resize mode side effect. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

kirillzyusko · 2026-03-09T17:58:23Z

Hey @thomasttvo

I reviewed your PR and I think it has breaking changes. Since we start to calculate keyboardVerticalOffset partially on our own -> all users that update from previous version will have breaking changes (i. e. the content will be pushed higher than expected).

I tend to think this is a breaking change and I don't want to created a release V2 just because of these changes. Do you think we can hide new functionality under feature flag/new prop?

For example automaticallyCalculateVerticalKeyboard/includeAbsoluteScreenPosition/whatever you-or-claude think is better and when it's true, then use new path for calculation?

Again, my concern is that onLayout and measureInWindow may produce different results. onLayout may not include Header/SafeArea etc. height. -- measureInWindow will account that spacing. Maybe we can add a new internal property like absoluteY which will be 0 by default, and when new prop is passed then we'll update it (via measure function) and we will always include it in calculations?

thomasttvo · 2026-03-09T18:22:05Z

makes sense @kirillzyusko let me see what I can do

The measureInWindow change was a breaking change for users who set keyboardVerticalOffset to their header height. This gates it behind an `automaticOffset` prop (default false) so existing behavior is preserved. When enabled, the view auto-detects its screen position and keyboardVerticalOffset becomes purely additive. Also moves example app settings from nav header to screen content area, updates E2E tests for both modes, and updates docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

kirillzyusko · 2026-03-10T14:25:24Z

There's also the argos failure, which probably wasn't caused by this PR

You can ignore them for now. Argos job is flacky a little bit and needs to be fixed (I'll handle it separately)

- Remove reMeasure + useGenericKeyboardHandler (unnecessary: keyboard open triggers onLayout which corrects stale measureInWindow values) - Remove runOnJS and useGenericKeyboardHandler imports - Simplify onLayout to single if/else without nested null checks - Scope onLayoutWorklet else branch to automaticOffset only (non-automatic mode uses parent-relative coords that are always correct) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove relativeKeyboardHeight comment (duplicates automaticOffset JSDoc) - Remove onLayout ref existence comment (self-evident from optional chain) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rewrite the automaticOffset else-branch comment to explain the full chain: why the if-branch skips updates, why automaticOffset needs the correction, and why height is preserved. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Split the single block comment into two focused comments — one per branch — so readers understand each path independently. Add ref safety comment on measureInWindow call. Remove debug console.log. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Position mode's outer view doesn't resize when the keyboard opens (only the inner view shifts via { bottom }), so onLayout won't re-fire to correct stale measureInWindow values from modal animation. Add useGenericKeyboardHandler to re-measure on keyboard start. Also: split onLayoutWorklet comments, add ref safety comment, simplify else-branch with spread, remove debug console.log. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Reverts example app and e2e test modifications to keep this PR focused on the core automaticOffset implementation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

New dedicated example screen showcasing automaticOffset in KeyboardAvoidingView, including a page-sheet Modal to test all three behavior modes (padding, height, position). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Testing confirmed measureInWindow returns correct coordinates at onLayout time in modals, making the useGenericKeyboardHandler re-measurement unnecessary. Also adds Auto/Manual toggle to the example screen and removes debug code. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The else-if branch for automaticOffset in height mode was not needed — the stale y=0 from measureInWindow gets corrected on the next onLayout while the keyboard is still closed. Height mode's shrunk-view bug exists regardless of this branch. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

thomasttvo · 2026-03-11T02:45:24Z

@kirillzyusko 🤦 , this is very strange. I can see the y=0 on initial load but now it quickly changes to a positive value the moment the modal finishes the animation, which means we don't need the extra logic. It wasn't doing that before, maybe it was just me hallucinating, or things got weird after rounds of hot reloads. I removed all the code that workarounds the y=0 for height and position mode, and added a separate screen for the Automatic Offset mode. Let me know what you think!

kirillzyusko

Looks good! Thank you for your contribution ❤️

kirillzyusko · 2026-03-11T12:36:45Z

FYI @thomasttvo it seems like it doesn't work with new architecture (FabricExample) + Modal:

Paper architecture works well. Is it a bug in measureInWindow?..

thomasttvo · 2026-03-11T17:18:38Z

@kirillzyusko on it! should have checked that we've been testing against Paper all this time.

kirillzyusko · 2026-03-11T17:24:39Z

@thomasttvo the problem seems to be in react-native and how measureInWindow is implemented on a new architecture. I'll prepare a fix in RN repo, no worries!

kirillzyusko · 2026-03-11T18:08:36Z

I opened a PR here: facebook/react-native#56062

) ## 📜 Description Automatically detect top border of `KeyboardAwareScrollView`. ## 💡 Motivation and Context Continue the epic with better discovery of component location on the screen and logical continuation of #1346 In this PR I started to detect relative position of `ScrollView`, so that I better understand if caret is not visible because it obscured by other elements (header etc.) It's still not perfectly implemented and there is still a "blind"/"dead" zone where text is already hidden but scroll doesn't happen. I'll fix it in following PRs but for now I just want to bring these changes to upcoming `1.21.0` release 🤞 We also can't use `measureInWindow` because it produces incorrect measurements, so we need to use our custom implementation that has been added in #1355 Significantly improves UI for behavior described in #1341 ## 📢 Changelog    ### JS - auto detect position of `KeyboardAwareScrollView` on the screen to better understand top border of the component relative to screen; ## 🤔 How Has This Been Tested? Tested manually on iPhone 17 Pro (iOS 26.2, simulator). ## 📸 Screenshots (if appropriate): https://github.com/user-attachments/assets/43fe233f-9c83-40c9-9642-a68e2d8e8e7c ## 📝 Checklist - [x] CI successfully passed - [x] I added new mocks and corresponding unit-tests if library API was changed

## 📜 Description Silent `could not fing view for tag` warning for `KeyboardAwareScrollView` (similarly how it works for `KeyboardAvoidingView` now). ## 💡 Motivation and Context This issue got introduced after #1352 (which was based on #1346) In certain cases `onLayout` may be triggered but view may be not laid out yet (if you use it with `react-native-pager` lazy). Since changes in #1352 were purely additional (we try to understand the position of element on the screen, but before these changes we always assumed we were in the top of the screen) I decided to wrap it for now in `try/catch` block. Silenting error is not a correct fix, but this is the best what we can do now - we will not spam logs when devs update the package (in #1346 we also used `catch` block), but yes, in certain cases detection of top border will not work (and it didn't work before, so it's fair enough to silent the error). Closes #1375 ## 📢 Changelog    ### JS - handle rejected promises within `try/catch` block; ## 🤔 How Has This Been Tested? Tested via e2e tests, I didn't test changes manually because I don't have a repro. ## 📝 Checklist - [x] CI successfully passed - [x] I added new mocks and corresponding unit-tests if library API was changed

thomasttvo force-pushed the fix/kav-modal-measure-in-window branch from 33bcd74 to 9436c60 Compare March 8, 2026 07:21

Remove unnecessary type assertion on internalRef

faf5e6f

Type useRef as View | null to avoid the MutableRefObject cast. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

thomasttvo force-pushed the fix/kav-modal-measure-in-window branch from 9436c60 to faf5e6f Compare March 8, 2026 07:22

thomasttvo marked this pull request as draft March 8, 2026 07:33

kirillzyusko reviewed Mar 8, 2026

View reviewed changes

Comment thread src/components/KeyboardAvoidingView/index.tsx Outdated

kirillzyusko self-assigned this Mar 8, 2026

kirillzyusko added 🐛 bug Something isn't working 🌎 modal Anything that involves Modal usage KeyboardAvoidingView 🧪 Anything related to KeyboardAvoidingView component labels Mar 8, 2026

thomasttvo changed the title ~~fix: use measureInWindow for correct KAV positioning in modals~~ WIP fix: use measureInWindow for correct KAV positioning in modals Mar 8, 2026

thomasttvo changed the title ~~WIP fix: use measureInWindow for correct KAV positioning in modals~~ fix: use measureInWindow for correct KAV positioning in modals Mar 8, 2026

thomasvo and others added 3 commits March 8, 2026 12:38

Add keyboardVerticalOffset toggle to example

401612e

Cycles through 0, 50, 100 to demonstrate the additive offset behavior. Shows "+N" in the header bar. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

thomasttvo marked this pull request as ready for review March 8, 2026 20:10

thomasttvo changed the title ~~fix: use measureInWindow for correct KAV positioning in modals~~ fix: use measureInWindow for correct KAV absolute positioning Mar 9, 2026

thomasvo and others added 3 commits March 9, 2026 10:29

fix: lint errors in import ordering and prettier formatting

5b3ca7e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

thomasttvo commented Mar 10, 2026

View reviewed changes

Comment thread src/components/KeyboardAvoidingView/index.tsx Outdated

thomasvo and others added 3 commits March 10, 2026 09:14

chore: remove redundant comments per review feedback

311bfae

- Remove relativeKeyboardHeight comment (duplicates automaticOffset JSDoc) - Remove onLayout ref existence comment (self-evident from optional chain) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

thomasttvo force-pushed the fix/kav-modal-measure-in-window branch from d96427c to ed904e4 Compare March 10, 2026 16:48

thomasttvo force-pushed the fix/kav-modal-measure-in-window branch from ed904e4 to 11ea978 Compare March 10, 2026 16:50

thomasttvo commented Mar 10, 2026

View reviewed changes

Comment thread src/components/KeyboardAvoidingView/index.tsx Outdated

thomasttvo commented Mar 10, 2026

View reviewed changes

Comment thread src/components/KeyboardAvoidingView/index.tsx Outdated

thomasvo and others added 5 commits March 10, 2026 10:19

revert: remove example and e2e changes per maintainer request

38e3ac2

Reverts example app and e2e test modifications to keep this PR focused on the core automaticOffset implementation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add KAV Automatic example screen with Modal

9e4d734

New dedicated example screen showcasing automaticOffset in KeyboardAvoidingView, including a page-sheet Modal to test all three behavior modes (padding, height, position). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove added comments from onLayoutWorklet

f19fbb3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

kirillzyusko approved these changes Mar 11, 2026

View reviewed changes

kirillzyusko merged commit 66e6278 into kirillzyusko:main Mar 11, 2026
21 checks passed

thomasttvo mentioned this pull request Mar 11, 2026

fix: handle broken measureInWindow #1355

Merged

2 tasks

This was referenced Mar 12, 2026

keyboardVerticalOffset is unreliable as useHeaderHeight produces different measurements for different phones #1356

Closed

fix: automatically detect top border of KeyboardAwareScrollView #1352

Merged

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

kirillzyusko mentioned this pull request Mar 18, 2026

fix: could not fing view for tag warning #1379

Merged

2 tasks

Uh oh!

Conversation

thomasttvo commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Example app

Test Plan

Uh oh!

Uh oh!

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

Uh oh!

📊 Package size report

Uh oh!

kirillzyusko commented Mar 8, 2026

Uh oh!

thomasttvo commented Mar 8, 2026

Uh oh!

thomasttvo commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

kirillzyusko commented Mar 9, 2026

Uh oh!

thomasttvo commented Mar 9, 2026

Uh oh!

kirillzyusko commented Mar 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thomasttvo commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kirillzyusko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kirillzyusko commented Mar 11, 2026

Uh oh!

thomasttvo commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kirillzyusko commented Mar 11, 2026

Uh oh!

kirillzyusko commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thomasttvo commented Mar 8, 2026 •

edited

Loading

github-actions Bot commented Mar 8, 2026 •

edited

Loading

thomasttvo commented Mar 8, 2026 •

edited

Loading

argos-ci Bot commented Mar 9, 2026 •

edited

Loading

thomasttvo commented Mar 11, 2026 •

edited

Loading

thomasttvo commented Mar 11, 2026 •

edited

Loading