TypeCellOS · matthewlipski · Aug 3, 2026 · Aug 6, 2026 · Aug 7, 2026 · Aug 7, 2026
diff --git a/docs/app/layout.tsx b/docs/app/layout.tsx
@@ -2,7 +2,7 @@ import { Footer } from "@/components/Footer";
 import { Provider } from "@/components/provider";
 import { getFullMetadata } from "@/lib/getFullMetadata";
 import { Analytics } from "@vercel/analytics/next";
-import { Metadata } from "next";
+import { Metadata, Viewport } from "next";
 import "./global.css";
 import "./gradients.css";
 import "./styles.css";
@@ -13,6 +13,16 @@ export const metadata: Metadata = getFullMetadata({
     "A beautiful text editor that just works. Easily add an editor to your app that users will love. Customize it with your own functionality like custom blocks or AI tooling.",
 });
 
+// Resizes the layout viewport (not just the visual viewport) when a virtual
+// keyboard opens, so `position: fixed` elements can be pinned to the top of the
+// keyboard. Must be set in the initial HTML, so it lives here rather than in an
+// example's App. Mirrors the examples' generated `index.html` viewport meta.
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  interactiveWidget: "resizes-content",
+};
+
 export default function Layout({ children }: LayoutProps<"/">) {
   return (
     <html lang="en" suppressHydrationWarning>

diff --git a/docs/content/docs/react/components/formatting-toolbar.mdx b/docs/content/docs/react/components/formatting-toolbar.mdx
@@ -38,3 +38,71 @@ The first element in the default Formatting Toolbar is the Block Type Select, an
 <Example name="ui-components/formatting-toolbar-block-type-items" />
 
 Here, we use the `FormattingToolbar` component but keep the default buttons (we don't pass any children). Instead, we pass our customized Block Type Select items using the `blockTypeSelectItems` prop.
+
+## Mobile Formatting Toolbar
+
+On touch devices, BlockNote's default UI replaces the floating Formatting Toolbar with a mobile Formatting Toolbar that sits just above the on-screen keyboard. It shows the same items as the regular Formatting Toolbar and is enabled by default - there's nothing to set up. Open any of the examples above on a phone to see it.
+
+### Viewport setup
+
+For the best behavior, add `interactive-widget=resizes-content` to your page's viewport meta tag:
+
+```html
+<meta
+  name="viewport"
+  content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+/>
+```
+
+The mobile Formatting Toolbar works with two page layouts. Which one you get depends on your app's layout:
+
+- **Scrolling document** (the default): the page scrolls as usual and BlockNote repositions the toolbar as you scroll.
+- **Scroll container**: the document itself doesn't scroll; a container pinned to the visual viewport scrolls instead, and the toolbar never has to move.
+
+### Scrolling document
+
+This is what you get without any changes to your app. The toolbar follows the visible area above the keyboard as the page scrolls. On iOS, mobile browsers only report visual viewport changes after the fact, so the toolbar can lag or jitter slightly while the page is scrolling. If that matters for your app, switch to a scroll container.
+
+### 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. This comes with some potential trade-offs though. Browser gestures that rely on document scrolling, like pull-to-refresh, may stop working and browser UI elements like the address bar, which normally hides and reappears as you scroll, may stay fixed. Note that these trade-offs are browser-dependent - some will have neither, while others will have both.
+
+To set this up, add the `bn-scroll-container` class to the element that wraps all your scrollable page content:
+
+```tsx
+<div className="bn-scroll-container">{/* nav, editor, page content... */}</div>
+```
+
+<Callout type="warning">
+  Your app should only ever have a single `bn-scroll-container` element. It's
+  pinned to the visual viewport with `position: fixed`, so multiple containers
+  would overlap each other. Wrap all your scrollable page content in one.
+</Callout>
+
+That's all the setup needed. These styles ship in BlockNote's stylesheet:
+
+```css
+html:has(.bn-scroll-container),
+body:has(.bn-scroll-container) {
+  overflow: hidden;
+}
+```
+
+This locks scrolling on `<html>` and `<body>` whenever a `bn-scroll-container` element is present. The container is then pinned to the visual viewport using the `--bn-vv-*` CSS variables, which BlockNote sets on `<html>` at runtime as the viewport changes:
+
+```css
+.bn-scroll-container {
+  position: fixed;
+  top: var(--bn-vv-top, 0px);
+  left: var(--bn-vv-left, 0px);
+  width: var(--bn-vv-width, 100vw);
+  height: var(--bn-vv-height, 100dvh);
+  overflow-y: auto;
+  -webkit-overflow-scrolling: touch;
+  overscroll-behavior: contain;
+}
+```
+
+These variables track the [visual viewport](https://developer.mozilla.org/en-US/docs/Web/API/VisualViewport) - the part of the page actually visible above the keyboard. 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.
+
+Because this layout changes how the whole page scrolls, the example can't be embedded here - open the [standalone example](https://playground.blocknotejs.org/ui-components/mobile-formatting-toolbar?hideMenu=true) on a phone instead. It puts a navigation bar, some static text, and the editor inside an element with the `bn-scroll-container` class, and the switch in the navigation bar toggles the pinned scroll container layout on and off so you can compare it with the default scrolling document. Select some text and scroll in each layout to see the difference.
diff --git a/examples/01-basic/01-minimal/index.html b/examples/01-basic/01-minimal/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Basic Setup</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/02-block-objects/index.html b/examples/01-basic/02-block-objects/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Displaying Document JSON</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/03-multi-column/index.html b/examples/01-basic/03-multi-column/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Multi-Column Blocks</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/04-default-blocks/index.html b/examples/01-basic/04-default-blocks/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Default Schema Showcase</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/05-removing-default-blocks/index.html b/examples/01-basic/05-removing-default-blocks/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Removing Default Blocks from Schema</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/06-block-manipulation/index.html b/examples/01-basic/06-block-manipulation/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Manipulating Blocks</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/07-selection-blocks/index.html b/examples/01-basic/07-selection-blocks/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Displaying Selected Blocks</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/08-ariakit/index.html b/examples/01-basic/08-ariakit/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Use with Ariakit</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/09-shadcn/index.html b/examples/01-basic/09-shadcn/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Use with ShadCN</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/10-localization/index.html b/examples/01-basic/10-localization/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Localization (i18n)</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/11-custom-placeholder/index.html b/examples/01-basic/11-custom-placeholder/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Change placeholder text</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/12-multi-editor/index.html b/examples/01-basic/12-multi-editor/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Multi-Editor Setup</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/13-custom-paste-handler/index.html b/examples/01-basic/13-custom-paste-handler/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Custom Paste Handler</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/14-editor-scrollable/index.html b/examples/01-basic/14-editor-scrollable/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Scrollable Editor</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/15-shadowdom/index.html b/examples/01-basic/15-shadowdom/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Shadow DOM</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/16-read-only-editor/index.html b/examples/01-basic/16-read-only-editor/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Read-only Editor</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/17-no-trailing-block/index.html b/examples/01-basic/17-no-trailing-block/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>No Trailing Block</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/01-basic/testing/index.html b/examples/01-basic/testing/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Test Editor</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/02-backend/01-file-uploading/index.html b/examples/02-backend/01-file-uploading/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Upload Files</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/02-backend/02-saving-loading/index.html b/examples/02-backend/02-saving-loading/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Saving &amp; Loading</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/02-backend/03-s3/index.html b/examples/02-backend/03-s3/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Upload Files to AWS S3</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/02-backend/04-rendering-static-documents/index.html b/examples/02-backend/04-rendering-static-documents/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Rendering static documents</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/03-ui-components/01-ui-elements-remove/index.html b/examples/03-ui-components/01-ui-elements-remove/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Removing UI Elements</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/03-ui-components/02-formatting-toolbar-buttons/index.html b/examples/03-ui-components/02-formatting-toolbar-buttons/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Adding Formatting Toolbar Buttons</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->

diff --git a/examples/03-ui-components/03-formatting-toolbar-block-type-items/index.html b/examples/03-ui-components/03-formatting-toolbar-block-type-items/index.html
@@ -1,7 +1,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
     <title>Adding Block Type Select Items</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->