docs: name the mobile toolbar layouts + add layout toggle to the example by YousefED · Pull Request #2985 · TypeCellOS/BlockNote

YousefED · 2026-08-19T10:48:46Z

Follow-up to #2939, targeting its branch. Docs/example-only — no behavior changes in @blocknote/react (two JSDoc comments reworded).

Why

The opt-in "smooth scrolling" setup was described three different ways (the docs called it a "workaround", the code comments "non-scrolling document", the example .scroll-host), which made the docs section hard to follow. This PR gives the two page layouts names and restructures the section around them:

Scrolling document (default) – the page scrolls, BlockNote repositions the toolbar as you scroll (slight lag/jitter).
Pinned scroll container (opt-in) – html/body locked, a container pinned to the visual viewport scrolls instead, toolbar is truly fixed.

"Pinned scroll container" names the one thing the host app has to add; "locked document" would name the precondition instead, and "jank-free mode" the outcome.

Changes

Docs – `formatting-toolbar.mdx`

Simple-first rewrite of Mobile Formatting Toolbar: intro (on by default on touch devices, nothing to set up) → two-bullet summary naming both layouts → ### Scrolling document → ### Pinned scroll container with the same two CSS rules as before, the --bn-vv-* vars (now also listing --bn-vv-scale) and the actionable trade-off (pull-to-refresh etc.). Headings give stable anchors (#scrolling-document, #pinned-scroll-container).

The embedded example broke the docs page → `docs: false`

The docs render examples inline (dynamic() import, no iframe), so this example's page-level CSS leaked into the docs page: html, body { overflow: hidden }, the full-viewport position: fixed .scroll-host, .bn-container { height: 300px } (hits the other two examples on the page) and .prose h2/p (collides with fumadocs' typography class). On the #2939 Vercel preview the lorem ipsum and demo editor are fixed over the prose and the page can't scroll.

Since a pinned-scroll-container layout inherently owns the whole page, it can't be embedded. Following the editor-scrollable / comments.mdx precedent, the example is now docs: false and the docs link to https://playground.blocknotejs.org/ui-components/mobile-formatting-toolbar?hideMenu=true. If you'd rather keep an embed, it needs an iframe-based one.

Example – layout toggle

A "Pinned scroll container" switch in the demo nav bar toggles the layout so both can be compared on a device. It's pure CSS: App.tsx toggles a pinned-scroll-container class on <html> (on <html> rather than <body> so the lock rule can scope both html and body without :has()), and style.css scopes the two rules under it, labelled "step 1" / "step 2". Defaults to on; comments say a real app applies the rules unconditionally. Verified in iPhone emulation: class/overflow/position flip correctly and the toolbar still lands above the keyboard with the host resized to the visual viewport.

Known/inherent: with the playground menu visible, the full-viewport fixed .scroll-host sits under the playground sidebar (hence ?hideMenu=true in the docs link).

Playground – `.mantine-AppShell-root { width: 100vw }` → `100%`

Separable. 100vw includes the vertical scrollbar, so any playground example taller than the viewport shows a horizontal scrollbar with classic/always-visible scrollbars (this example exposes it when the toggle is off; pinned mode only masks it because the document can't scroll). Reproduced with real scrollbars (clientWidth 1265 vs scrollWidth 1280) and verified fixed.

Housekeeping

README, JSDoc in MobileFormattingToolbarController / useVirtualKeyboard, and example comments aligned with the naming (also fixes the stale DemoChrome → DummyUI.tsx reference).
examples.gen.tsx regenerated via vp run gen — it was already stale vs. the example README on the branch.

Verification

node docs/validate-links.mjs → 0 errors; docs page renders (200) with the new anchors, no overlay.
pnpm run lint clean.
Playwright emulation (iPhone 13, Chromium) for the toggle and toolbar placement; desktop with real scrollbars for the playground fix.

🤖 Generated with Claude Code

Introduce "scrolling document" (default) vs "pinned scroll container" (opt-in) as the names for the two page layouts the mobile formatting toolbar supports, and restructure the docs section around them. - Docs: simple-first rewrite of the Mobile Formatting Toolbar section (default layout, then the opt-in layout with its two CSS rules). - Example: stop embedding it in the docs (`docs: false`) - its page-level CSS (html/body overflow, full-viewport fixed scroll host, `.prose` rules) leaks into the docs page since examples render inline. Link to the standalone playground example instead. - Example: add a nav-bar switch that toggles the pinned scroll container layout via a class on <html>, so both layouts can be compared. - Playground: `.mantine-AppShell-root` width 100vw -> 100%, which caused a horizontal scrollbar on any example taller than the viewport. - Align README, JSDoc and example comments with the new naming; regenerate examples.gen.tsx.

vercel · 2026-08-19T10:48:52Z

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

Project	Deployment	Actions	Updated (UTC)
blocknote	Ready	Preview	Aug 19, 2026 10:50am
blocknote-website	Ready	Preview	Aug 19, 2026 10:50am

coderabbitai · 2026-08-19T10:49:06Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e3c2f9de-4b31-4c60-b888-bc077cf1e85c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

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

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

pkg-pr-new · 2026-08-19T10:52:33Z

Open in StackBlitz

@blocknote/ariakit

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

@blocknote/code-block

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

@blocknote/core

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

@blocknote/diagram-block

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

@blocknote/mantine

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

@blocknote/math-block

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

@blocknote/react

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

@blocknote/server-util

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

@blocknote/shadcn

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

@blocknote/xl-ai

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

@blocknote/xl-docx-exporter

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

@blocknote/xl-email-exporter

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

@blocknote/xl-multi-column

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

@blocknote/xl-odt-exporter

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

@blocknote/xl-pdf-exporter

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

commit: 8eb53e3

github-actions · 2026-08-19T10:55:52Z

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

matthewlipski

Good changes, left 2 comments

matthewlipski · 2026-08-19T11:48:03Z

+
+### Pinned scroll container
+
+In this layout, `<html>` and `<body>` are locked and all page content lives inside a single scroll container that BlockNote keeps aligned with the visual viewport. Since the document never scrolls, the toolbar can stay at a truly fixed position and the lag/jitter disappears. The trade-off is that browser gestures which rely on document scrolling, like pull-to-refresh, no longer work.


2 small things:

The other main trade-off is that the browser UI may no longer show/hide on scroll

Different browsers may have both of these issues, only 1 of them, or neither. So I would change the framing of the last sentence and say these trade-offs may occur depending on the browser used.

Would be a good addition, if you can find a good way to phrase this. "Browser UI" is very generic / not clear to me as a reader what this is

matthewlipski · 2026-08-19T11:49:31Z

 ```

-BlockNote keeps the `--bn-vv-*` variables up to date as the keyboard opens/closes and the user zooms or pans, so both the toolbar and your scroll container stay aligned with the visual viewport without any JavaScript on your end.
+BlockNote keeps `--bn-vv-top`, `--bn-vv-left`, `--bn-vv-width`, and `--bn-vv-height` (plus `--bn-vv-scale`, the pinch-zoom factor) up to date as the keyboard opens and closes and as the user pans or zooms, so the scroll container always lines up with the visible area above the keyboard without any JavaScript on your end.


Perhaps worth saying that these variables track the visual viewport

sounds good

vercel Bot deployed to Preview – blocknote August 19, 2026 10:48 View deployment

vercel Bot deployed to Preview – blocknote-website August 19, 2026 10:50 View deployment

YousefED requested a review from matthewlipski August 19, 2026 10:50

matthewlipski reviewed Aug 19, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

docs: name the mobile toolbar layouts + add layout toggle to the example - #2985

docs: name the mobile toolbar layouts + add layout toggle to the example#2985
YousefED wants to merge 1 commit into
mobile-toolbar-demofrom
mobile-toolbar-docs-layout-naming

YousefED commented Aug 19, 2026

Uh oh!

vercel Bot commented Aug 19, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 19, 2026

Review skipped

Uh oh!

pkg-pr-new Bot commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026

Built to branch `gh-pages` at 2026-08-19 10:55 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

matthewlipski left a comment

Uh oh!

matthewlipski Aug 19, 2026

Uh oh!

YousefED Aug 19, 2026

Uh oh!

matthewlipski Aug 19, 2026

Uh oh!

YousefED Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		### Pinned scroll container

		In this layout, `<html>` and `<body>` are locked and all page content lives inside a single scroll container that BlockNote keeps aligned with the visual viewport. Since the document never scrolls, the toolbar can stay at a truly fixed position and the lag/jitter disappears. The trade-off is that browser gestures which rely on document scrolling, like pull-to-refresh, no longer work.

Uh oh!

Uh oh!

Conversation

YousefED commented Aug 19, 2026

Why

Changes

Docs – formatting-toolbar.mdx

The embedded example broke the docs page → docs: false

Example – layout toggle

Playground – .mantine-AppShell-root { width: 100vw } → 100%

Housekeeping

Verification

Uh oh!

vercel Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 19, 2026

Review skipped

Uh oh!

pkg-pr-new Bot commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026

Built to branch gh-pages at 2026-08-19 10:55 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

matthewlipski left a comment

Choose a reason for hiding this comment

Uh oh!

matthewlipski Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

YousefED Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

matthewlipski Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

YousefED Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Docs – `formatting-toolbar.mdx`

The embedded example broke the docs page → `docs: false`

Playground – `.mantine-AppShell-root { width: 100vw }` → `100%`

vercel Bot commented Aug 19, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-08-19 10:55 UTC.
Preview will be ready when the GitHub Pages deployment is complete.