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,40 @@ 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 mobile, BlockNote's default UI automatically shows a dedicated formatting toolbar pinned just above the on-screen keyboard - no setup needed. It renders the same items as the regular Formatting Toolbar, but stays anchored to the keyboard so it's always reachable while editing on a touch device. Try it in any of the previous examples to see it in action!
+
+Due to browser limitations, scrolling the page can cause the mobile Formatting Toolbar to appear laggy or jittery. BlockNote offers a workaround for these limitations, which you can see below.
+
+<Example name="ui-components/mobile-formatting-toolbar" />
+
+Here, the lag/jitter is eliminated, at the cost of `<body>` and its ancestors no longer being scrollable. Instead, all scrollable page content must be in a scrollable container that's a descendant of `<body>`.
+
+To set this up, first lock scrolling on the document itself. This prevents the browser from scrolling `<html>`/`<body>`, which is what causes the toolbar to jitter:
+
+```css
+html,
+body {
+  margin: 0;
+  overflow: hidden;
+}
+```
+
+Then, make your scroll container (`.scroll-host` in the demo) the element that actually scrolls. It's pinned to the visual viewport using the `--bn-vv-*` CSS variables that BlockNote publishes on the root element (`--bn-vv-top`, `--bn-vv-left`, `--bn-vv-width`, and `--bn-vv-height`), so it always lines up with the visible area above the keyboard:
+
+```css
+.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;
+}
+```
+
+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.
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
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
+
+On mobile, BlockNote's default UI automatically shows a formatting toolbar pinned above the virtual keyboard - no setup needed. This example demos the opt-in, CSS-only "non-scrolling document" setup (locking `html`/`body` scroll and sizing a `.scroll-host` to the visual viewport), which keeps the toolbar smoothly pinned while scrolling.
+
+**Relevant Docs:**
+
+- [Changing the Formatting Toolbar](/docs/react/components/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,44 @@
+import "@blocknote/core/fonts/inter.css";
+import { useCreateBlockNote } from "@blocknote/react";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+
+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 — it stays " +
+      "pinned above the keyboard because the document itself doesn't scroll.",
+  },
+  ...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 });
+
+  return (
+    // To make the formatting toolbar scrolling smoother, we lock the `document.body` scrolling
+    // using CSS so we can use `position: fixed` on the toolbar. Therefore, we need to use a
+    // descendant element for scrolling.
+    <div className="scroll-host">
+      <NavBar />
+      <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 />
+      </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,78 @@
+import { useState } from "react";
+
+function HamburgerMenu() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="hamburger">
+      <button
+        type="button"
+        className="hamburger-button"
+        aria-label="Menu"
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+      >
+        <span />
+        <span />
+        <span />
+      </button>
+      {open && (
+        <nav className="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() {
+  return (
+    <header className="top-nav">
+      <HamburgerMenu />
+      <span className="top-nav-title">Lorem Ipsum</span>
+    </header>
+  );
+}
+
+/** A block of static page text, to sit around the editor. */
+export function StaticText() {
+  return (
+    <section className="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>
+  );
+}
diff --git a/examples/03-ui-components/14-mobile-formatting-toolbar/src/style.css b/examples/03-ui-components/14-mobile-formatting-toolbar/src/style.css
@@ -0,0 +1,133 @@
+html,
+body {
+  margin: 0;
+  overflow: hidden;
+}
+
+/* Fixed-height, internally scrollable editor — a nested scroll container inside
+   the page's `.scroll-host`, to check nested scrolling works. */
+.bn-container {
+  height: 300px;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.bn-editor {
+  height: 100%;
+  overflow: auto;
+}
+
+/* --- App shell (see DemoChrome) --- */
+
+.top-nav {
+  position: sticky;
+  top: 0;
+  z-index: 20;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  height: 48px;
+  padding: 0 12px;
+  background: #1a1a1a;
+  color: #fff;
+}
+
+.top-nav-title {
+  font: 600 15px/1 sans-serif;
+}
+
+.hamburger {
+  position: relative;
+}
+
+.hamburger-button {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: 5px;
+  width: 44px;
+  height: 44px;
+  margin: -10px;
+  padding: 0;
+  background: none;
+  border: none;
+  cursor: pointer;
+}
+
+.hamburger-button span {
+  display: block;
+  width: 22px;
+  height: 2px;
+  border-radius: 1px;
+  background: #fff;
+}
+
+.hamburger-menu {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  display: flex;
+  flex-direction: column;
+  min-width: 180px;
+  padding: 8px;
+  background: #fff;
+  color: #111;
+  border-radius: 8px;
+  box-shadow: 0 6px 20px rgb(0 0 0 / 0.15);
+}
+
+.hamburger-menu a {
+  display: flex;
+  align-items: center;
+  min-height: 44px;
+  padding: 8px 10px;
+  color: inherit;
+  text-decoration: none;
+  border-radius: 6px;
+}
+
+.hamburger-menu a:hover {
+  background: #f0f0f0;
+}
+
+.app-main {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  max-width: 720px;
+  margin: 0 auto;
+  padding: 16px;
+}
+
+.prose h2 {
+  margin: 0 0 8px;
+  font: 600 18px/1.2 sans-serif;
+}
+
+.prose p {
+  margin: 0 0 8px;
+  font: 14px/1.6 sans-serif;
+  color: #333;
+}
+
+/* A top-level wrapper div is the scroll container (the document itself doesn't
+   scroll — `html`/`body` are locked with `overflow: hidden` above), pinned to
+   the visual viewport rectangle via the `--bn-vv-*` variables the mobile
+   toolbar controller publishes, so it sits directly above the keyboard on iOS —
+   where the layout viewport doesn't resize and can be left with a nonzero
+   `offsetTop`. */
+.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;
+  /* Stop overscroll at the boundary from chaining to the document. Without
+     this, dragging past the bottom on iOS rubber-bands the whole page, which
+     shifts the visual viewport (repinning the host mid-bounce → jitter) and
+     surfaces a second, document-level scrollbar. */
+  overscroll-behavior: contain;
+}
diff --git a/...l-mobile-formatting-toolbar/vite-env.d.ts → ...bile-formatting-toolbar/src/vite-env.d.ts b/...l-mobile-formatting-toolbar/vite-env.d.ts → ...bile-formatting-toolbar/src/vite-env.d.ts
diff --git a/...l-mobile-formatting-toolbar/tsconfig.json → ...4-mobile-formatting-toolbar/tsconfig.json b/...l-mobile-formatting-toolbar/tsconfig.json → ...4-mobile-formatting-toolbar/tsconfig.json
diff --git a/...bile-formatting-toolbar/src/vite-env.d.ts → ...4-mobile-formatting-toolbar/vite-env.d.ts b/...bile-formatting-toolbar/src/vite-env.d.ts → ...4-mobile-formatting-toolbar/vite-env.d.ts
diff --git a/...-mobile-formatting-toolbar/vite.config.ts → ...-mobile-formatting-toolbar/vite.config.ts b/...-mobile-formatting-toolbar/vite.config.ts → ...-mobile-formatting-toolbar/vite.config.ts