TypeCellOS · matthewlipski · Aug 3, 2026 · Aug 6, 2026 · Aug 7, 2026 · Aug 7, 2026
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 `useVisualViewport` hook, which locks document scroll so the toolbar stays 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,48 @@
+import "@blocknote/core/fonts/inter.css";
+import { useCreateBlockNote, useVisualViewport } 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 });
+
+  // Opt into the "non-scrolling document" behavior: locks document scroll so the
+  // toolbar stays smoothly pinned above the keyboard during scroll, and publishes
+  // the `--bn-vv-*` variables this `.scroll-host` is sized against.
+  useVisualViewport();
+
+  return (
+    // The document itself doesn't scroll — `useVisualViewport` locks it and pins
+    // this `.scroll-host` to the visual viewport via the `--bn-vv-*` variables.
+    <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,124 @@
+html,
+body {
+  margin: 0;
+}
+
+/* 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: space-between;
+  width: 22px;
+  height: 16px;
+  padding: 0;
+  background: none;
+  border: none;
+  cursor: pointer;
+}
+
+.hamburger-button span {
+  display: block;
+  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 {
+  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 — `useVisualViewport` locks it), pinned to the visual viewport
+   rectangle via the `--bn-vv-*` variables it 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/...bile-formatting-toolbar/src/vite-env.d.ts → ...bile-formatting-toolbar/src/vite-env.d.ts b/...bile-formatting-toolbar/src/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/...l-mobile-formatting-toolbar/vite-env.d.ts → ...4-mobile-formatting-toolbar/vite-env.d.ts b/...l-mobile-formatting-toolbar/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
diff --git a/packages/ariakit/src/menu/Menu.tsx b/packages/ariakit/src/menu/Menu.tsx
@@ -11,13 +11,18 @@ import {
 
 import { assertEmpty, mergeCSSClasses } from "@blocknote/core";
 import { ComponentProps } from "@blocknote/react";
-import { forwardRef } from "react";
+import { createContext, forwardRef, useContext } from "react";
+
+const PortalRootContext = createContext<HTMLElement | null | undefined>(
+  undefined,
+);
 
 export const Menu = (props: ComponentProps["Generic"]["Menu"]["Root"]) => {
   const {
     children,
     onOpenChange,
     position,
+    portalRoot,
     sub: _sub, // unused
     ...rest
   } = props;
@@ -30,7 +35,9 @@ export const Menu = (props: ComponentProps["Generic"]["Menu"]["Root"]) => {
       setOpen={onOpenChange}
       virtualFocus={true}
     >
-      {children}
+      <PortalRootContext.Provider value={portalRoot}>
+        {children}
+      </PortalRootContext.Provider>
     </AriakitMenuProvider>
   );
 };
@@ -48,10 +55,13 @@ export const MenuDropdown = forwardRef<
 
   assertEmpty(rest);
 
+  const portalRoot = useContext(PortalRootContext);
+
   return (
     <AriakitMenu
       unmountOnHide={true}
       className={mergeCSSClasses("bn-ak-menu", className || "")}
+      portalElement={portalRoot ?? undefined}
       ref={ref}
     >
       {children}