fix: Scrolling to bottom of page on iOS

[matthewlipski]

Summary

This PR partially fixes this issue in #3031. You can now scroll to the bottom of the page again, but there is a lot of jitter once the bottom of the page is reached.

This is because the core fix to the iOS gap issue is the same. iOS has extra space below body for scrolling which the formatting toolbar cannot follow the virtual keyboard into when scrolling down. So whenever we scroll further than the bottom of body, we scroll back up to it. This "snap back" is what causes the jitter. The aforementioned issue was due to the scroll position at the bottom of body not taking the height of the virtual keyboard into consideration, which is fixed in this PR.

I tried an alternative approach which tried to prevent the "snap back" behaviour by preventing touch events from propagating into scroll events, so that we could prevent the scroll before it happens rather than snapping back to a previous position after it happens. However, this resulted in a ton of extra complexity as it had to account for things like dragging momentum, yet didn't meaningfully help with the jitter.

Rationale

See this issue

Changes

Updated useVirtualKeyboard hook.

Impact

I'm not convinced this results in better UX than just having the gap on iOS. The jitteriness imo is more annoying from a UX perspective.

Testing

Given we elected not to include iOS emulation in our automated tests, tests have not been added as they require an iOS environment to reproduce.

Screenshots/Video

ScreenRecording_09-17-2026.12-20-58_1.MP4

Checklist

• Code follows the project's coding standards.
• Unit tests covering the new feature have been added.
• All existing tests pass.
• The documentation has been updated to reflect the new feature

Additional Notes

N/A

Summary by CodeRabbit

• Bug Fixes
  • Improved mobile keyboard scrolling behavior in Safari.
  • Prevented document scrolling from being incorrectly clipped when the on-screen keyboard opens, during orientation changes, and as the keyboard closes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
blocknote	Ready	Preview	Sep 17, 2026 1:45pm UTC
blocknote-website	Ready	Preview	Sep 17, 2026 1:45pm UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 93c871b2-2bc4-433e-bd0c-a1015a5ef3b9

📥 Commits

Reviewing files that changed from the base of the PR and between 3ef29a8 and 28bc808.

📒 Files selected for processing (1)

• packages/react/src/components/FormattingToolbar/useVirtualKeyboard.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The virtual keyboard hook now retains an unclipped keyboard height for Safari viewport calculations. It applies document scroll clamping only while the keyboard is open and clears the retained value after closure, orientation changes, or cleanup.

Changes

Virtual Keyboard Scroll

Layer / File(s)	Summary
Keyboard-open scroll clamping packages/react/src/components/FormattingToolbar/useVirtualKeyboard.ts	The hook retains the scaled unclipped keyboard height, recalculates the clamped scroll limit, and updates the retained value when the layout viewport resizes. It resets the value on keyboard close, orientation change, and cleanup.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 28bc8

The scroll-clamping change has no confirmed merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: fixing scrolling to the bottom of the page on iOS.
Description check	✅ Passed	The description includes all required sections and explains the rationale, changes, impact, testing limits, and observed jitter. It also records that tests were not added because the issue requires an…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit watched the keyboard rise
And measured clouds behind Safari’s skies
The scroll stayed within its careful track
While unclipped heights kept limits back
When keyboards slept, the state was cleared
And tidy viewport paths appeared}

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/@blocknote/ariakit@3094

@blocknote/code-block

npm i https://pkg.pr.new/@blocknote/code-block@3094

@blocknote/core

npm i https://pkg.pr.new/@blocknote/core@3094

@blocknote/diagram-block

npm i https://pkg.pr.new/@blocknote/diagram-block@3094

@blocknote/mantine

npm i https://pkg.pr.new/@blocknote/mantine@3094

@blocknote/math-block

npm i https://pkg.pr.new/@blocknote/math-block@3094

@blocknote/react

npm i https://pkg.pr.new/@blocknote/react@3094

@blocknote/server-util

npm i https://pkg.pr.new/@blocknote/server-util@3094

@blocknote/shadcn

npm i https://pkg.pr.new/@blocknote/shadcn@3094

@blocknote/xl-ai

npm i https://pkg.pr.new/@blocknote/xl-ai@3094

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/@blocknote/xl-docx-exporter@3094

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/@blocknote/xl-email-exporter@3094

@blocknote/xl-multi-column

npm i https://pkg.pr.new/@blocknote/xl-multi-column@3094

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/@blocknote/xl-odt-exporter@3094

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/@blocknote/xl-pdf-exporter@3094

@blocknote/xl-typst-exporter

npm i https://pkg.pr.new/@blocknote/xl-typst-exporter@3094

commit: 3ef29a8

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://TypeCellOS.github.io/BlockNote/pr-preview/pr-3094/
Built to branch gh-pages at 2026-09-17 10:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[nperez0111]

Is there a way to simplify this logic, it's getting to be a bit of a mess, maybe it can be simpler to cache the maximum instead of of the unclippedKeyboarHeight instead. Presumably you want the absolute maximum and for it to go no further? Unsure, what we can do here

[matthewlipski]

Closing as the jitter caused by these changes at the bottom of the page makes for a worse overall UX than just having the gap between the keyboard and formatting toolbar.