TypeCellOS · matthewlipski · Aug 3, 2026 · Aug 6, 2026 · Aug 7, 2026 · Aug 7, 2026
diff --git a/docs/content/docs/react/components/formatting-toolbar.mdx b/docs/content/docs/react/components/formatting-toolbar.mdx
@@ -38,3 +38,60 @@ 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.
+
+The mobile Formatting Toolbar works with two page layouts. Which one you get is decided purely by your app's CSS:
+
+- **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. 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. Since the document no longer scrolls, this comes with some potential trade-offs. 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-host` class to your scroll container:
+
+```tsx
+<div className="bn-scroll-host">{/* nav, editor, page content... */}</div>
+```
+
+<Callout type="warning">
+  Your app should only ever have a single `bn-scroll-host` element. It's pinned
+  to the visual viewport with `position: fixed`, so multiple hosts would overlap
+  each other. Wrap all your scrollable page content in one host.
+</Callout>
+
+That's all the setup needed. BlockNote injects the following styles for you:
+
+```css
+html:has(.bn-scroll-host),
+body:has(.bn-scroll-host) {
+  overflow: hidden;
+}
+```
+
+This locks scrolling on `<html>` and `<body>` whenever a `bn-scroll-host` element is present. It's then pinned to the visual viewport using the `--bn-vv-*` CSS variables that BlockNote publishes on `<html>`:
+
+```css
+.bn-scroll-host {
+  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 a container with the `bn-scroll-host` 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/03-ui-components/14-experimental-mobile-formatting-toolbar/README.md b/examples/03-ui-components/14-experimental-mobile-formatting-toolbar/README.md
diff --git a/examples/03-ui-components/14-experimental-mobile-formatting-toolbar/src/App.tsx b/examples/03-ui-components/14-experimental-mobile-formatting-toolbar/src/App.tsx
diff --git a/examples/03-ui-components/14-experimental-mobile-formatting-toolbar/src/style.css b/examples/03-ui-components/14-experimental-mobile-formatting-toolbar/src/style.css
diff --git a/...mobile-formatting-toolbar/.bnexample.json → ...mobile-formatting-toolbar/.bnexample.json b/...mobile-formatting-toolbar/.bnexample.json → ...mobile-formatting-toolbar/.bnexample.json
@@ -1,6 +1,6 @@
 {
   "playground": true,
-  "docs": true,
+  "docs": false,
   "author": "areknawo",
   "tags": [
     "Intermediate",

diff --git a/examples/03-ui-components/14-mobile-formatting-toolbar/README.md b/examples/03-ui-components/14-mobile-formatting-toolbar/README.md
@@ -0,0 +1,8 @@
+# Mobile Formatting Toolbar
+
+This example demos the opt-in **scroll container** layout: adding the `bn-scroll-host` class to your scroll container locks `html`/`body` scrolling and pins the container to the visual viewport (BlockNote injects the styles), so the toolbar stays perfectly in place while scrolling and zooming. Use the switch in the nav bar to toggle it off and compare it with the default scrolling document layout.
+
+**Relevant Docs:**
+
+- [Mobile Formatting Toolbar](/docs/react/components/formatting-toolbar#mobile-formatting-toolbar)
+- [Editor Setup](/docs/getting-started/editor-setup)
diff --git a/...ntal-mobile-formatting-toolbar/index.html → ...s/14-mobile-formatting-toolbar/index.html b/...ntal-mobile-formatting-toolbar/index.html → ...s/14-mobile-formatting-toolbar/index.html
@@ -2,7 +2,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Experimental Mobile Formatting Toolbar</title>
+    <title>Mobile Formatting Toolbar</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
     </script>

diff --git a/...mental-mobile-formatting-toolbar/main.tsx → ...nts/14-mobile-formatting-toolbar/main.tsx b/...mental-mobile-formatting-toolbar/main.tsx → ...nts/14-mobile-formatting-toolbar/main.tsx
diff --git a/...al-mobile-formatting-toolbar/package.json → ...14-mobile-formatting-toolbar/package.json b/...al-mobile-formatting-toolbar/package.json → ...14-mobile-formatting-toolbar/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@blocknote/example-ui-components-experimental-mobile-formatting-toolbar",
+  "name": "@blocknote/example-ui-components-mobile-formatting-toolbar",
   "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
   "type": "module",
   "private": true,

diff --git a/examples/03-ui-components/14-mobile-formatting-toolbar/src/App.tsx b/examples/03-ui-components/14-mobile-formatting-toolbar/src/App.tsx
@@ -0,0 +1,63 @@
+import "@blocknote/core/fonts/inter.css";
+import { useCreateBlockNote } from "@blocknote/react";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import { useState } from "react";
+
+import "./style.css";
+import { StaticText, NavBar } from "./DummyUI";
+
+// Enough content that the editor actually overflows, so scrolling is testable.
+const initialContent = [
+  { type: "paragraph" as const, content: "Welcome to this demo!" },
+  {
+    type: "paragraph" as const,
+    content:
+      "Select some text to bring up the toolbar, then scroll. With the pinned " +
+      "scroll container layout on, it stays put because the document itself " +
+      "doesn't scroll. Toggle it off in the nav bar to compare.",
+  },
+  ...Array.from({ length: 20 }, (_, i) => ({
+    type: "paragraph" as const,
+    content:
+      `Filler paragraph ${i + 1}. Select some text here and bring up the ` +
+      "keyboard to see the toolbar sit above it.",
+  })),
+];
+
+export default function App() {
+  const editor = useCreateBlockNote({ initialContent });
+  // A second editor, to check the mobile toolbar still works with multiple
+  // editors on a page: the scroll-host styles are injected only once and each
+  // editor tracks the shared visual viewport independently.
+  const secondEditor = useCreateBlockNote({ initialContent });
+
+  // Which element scrolls the page. The "pinned scroll container" layout is
+  // opt-in via a single class: adding `bn-scroll-host` to the scroll container
+  // makes BlockNote's injected styles lock document scroll and pin the container
+  // to the visual viewport. Switching layouts is therefore just adding/removing
+  // the class - a real app would apply it unconditionally, the switch is only
+  // here so you can compare both.
+  const [scrollMode, setScrollMode] = useState<
+    "scrolling-document" | "scroll-container"
+  >("scroll-container");
+
+  return (
+    <div
+      className={
+        scrollMode === "scroll-container" ? "bn-scroll-host" : undefined
+      }
+    >
+      <NavBar scrollMode={scrollMode} onScrollModeChange={setScrollMode} />
+      <main className="app-main">
+        <StaticText />
+        {/* On mobile, the default UI automatically shows the mobile formatting
+            toolbar above the keyboard - no extra setup needed. */}
+        <BlockNoteView editor={editor} />
+        <StaticText />
+        <BlockNoteView editor={secondEditor} />
+        <StaticText />
+      </main>
+    </div>
+  );
+}
diff --git a/examples/03-ui-components/14-mobile-formatting-toolbar/src/DummyUI.tsx b/examples/03-ui-components/14-mobile-formatting-toolbar/src/DummyUI.tsx
@@ -0,0 +1,100 @@
+import { useState } from "react";
+
+function HamburgerMenu() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="dummy-hamburger">
+      <button
+        type="button"
+        className="dummy-hamburger-button"
+        aria-label="Menu"
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+      >
+        <span />
+        <span />
+        <span />
+      </button>
+      {open && (
+        <nav className="dummy-hamburger-menu">
+          <a href="#">Home</a>
+          <a href="#">Documents</a>
+          <a href="#">Shared with me</a>
+          <a href="#">Settings</a>
+        </nav>
+      )}
+    </div>
+  );
+}
+
+export function NavBar(props: {
+  scrollMode: "scrolling-document" | "scroll-container";
+  onScrollModeChange: (
+    scrollContainer: "scrolling-document" | "scroll-container",
+  ) => void;
+}) {
+  return (
+    <header className="dummy-top-nav">
+      <HamburgerMenu />
+      <span className="dummy-top-nav-title">Lorem Ipsum</span>
+      {/* Switches between the default "scrolling document" layout and the
+          "pinned scroll container" layout, to compare the toolbar in both. */}
+      <button
+        type="button"
+        className="dummy-layout-toggle"
+        aria-pressed={props.scrollMode === "scroll-container"}
+        onClick={() =>
+          props.onScrollModeChange(
+            props.scrollMode === "scroll-container"
+              ? "scrolling-document"
+              : "scroll-container",
+          )
+        }
+      >
+        Pinned scroll container
+        <span className="dummy-layout-toggle-track" aria-hidden="true" />
+      </button>
+    </header>
+  );
+}
+
+/** A block of static page text, to sit around the editor. */
+export function StaticText() {
+  return (
+    <section className="dummy-prose">
+      <h2>Lorem Ipsum</h2>
+      <p>
+        Elit ipsum qui deserunt deserunt. Qui labore eu esse veniam excepteur.
+        Aute ipsum qui dolore in ipsum commodo adipisicing velit. Qui
+        consectetur et cupidatat consectetur sunt anim excepteur reprehenderit
+        sunt quis magna aliqua laborum. Lorem irure est ipsum ea nisi incididunt
+        culpa qui consequat eiusmod deserunt ipsum nostrud velit laboris.
+      </p>
+      <p>
+        Culpa quis id ipsum enim proident dolore non. Ad occaecat nostrud
+        eiusmod pariatur occaecat nisi voluptate nulla. Nisi quis ut esse ex
+        reprehenderit Lorem tempor ex tempor id sit officia. Commodo sunt sint
+        aliqua quis reprehenderit. Occaecat id ad dolor officia qui sunt dolor.
+        Consectetur magna excepteur in minim pariatur qui elit in sit consequat
+        aliquip voluptate laboris. Reprehenderit et eu dolor ex cupidatat aliqua
+        in elit anim eiusmod et adipisicing. Cupidatat fugiat fugiat amet duis.
+      </p>
+      <p>
+        Voluptate quis dolor ipsum commodo fugiat sit tempor tempor non aliqua
+        qui. Veniam consectetur mollit consequat exercitation sit ad. Lorem amet
+        deserunt qui sint et. Sint aute cillum aliqua pariatur cillum id.
+        Consectetur proident Lorem qui laborum id in sit. Aute aute irure nisi
+        est veniam Lorem. Anim labore irure ut sit mollit velit et duis veniam
+        ipsum aliquip.
+      </p>
+      <p>
+        Occaecat dolore excepteur qui proident laborum. Dolor deserunt cillum
+        veniam nulla minim eu in est aute nulla anim incididunt ea. Anim aliquip
+        aute duis aliqua eu pariatur est dolor magna Lorem dolore do sunt
+        aliquip est. Laborum pariatur fugiat do reprehenderit tempor cupidatat
+        proident ipsum ad dolor laboris.
+      </p>
+    </section>
+  );
+}